Software READ THIS FIRST 
Notes for Sun™ fUNIX Release 3.4 




Release 3.4 incorporates fixes to bugs found in previous releases. It also includes the new SunPro optional software, 
pnh a nr.p.m p.nts to the SunView, graphics, and networking software, a kernel enhancement, and additions to the 
/etc/termcap file. 



Getting Help 

Should you have any problems while installing or using your system, call Sun Technical Support at 800-USA-4SUN 
(800-872-4786). From Canada, call 800-225-2615. Have your system’s model and serial numbers ready to give the 
dispatcher. Questions also can be sent by electronic mail to sun! hotline. Your mail should include your name, com- 
pany, phone number, system model number, and serial number, a description of your problem, and software release 
number. This service is provided at no additional charge for systems under warranty or covered by a support agree- 
ment. If you have questions about Sim’s support services or your shipment, call your sales representative. 

Notes for the 3.4 Release 

Uninstall Unavailable in This Release 

The 3.4 release does not provide uninstall capabilities. Therefore, it is strongly advised that you do a full backup 
of your system before installing Release 3.4, in case you need to back out of 3.4 and reinstall a prior version of 
the operating system. 



Manual Pages Attached 

The 3.4 manual page set is attached to this Read This First. These man pages were intended to be the last part of 
Appendix C of the Release 3.4 Manual for the Sun Workstation. Please insert the man pages into your Release 
3.4 manual after the tables in Appendix C. 



SunPro Installation Problem 

SunPro installation fails on standalones and on heterogeneous servers. If you try to install SunPro as follows: 



§ install_sunpro 



the system tries to install the software, but ultimately fails, giving messages such as 

mv: /pub/ lib /compile: Cannot access: No such file or directory 
mV; /pub/lib/cpp : Cannot access: No Such file or directory 
mv: /pub/bin/ld: Cannot access: No such file or directory 
mv: /pub/bin /make : Cannot access: No such file or directory 
/usr/man/manl/make.l: Permission denied. 

For this release, you should do the work of the script manually or fix it up for the local environment 
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For a Sun-2 or Sun-3 standalone system, do the following: 

1. Bring the system down with the shutdown command. 

2 Change your working directory to the SunPro directory by entering: 


r ' ; x, x. ; x; : ;.;x : 1 ;x : £v ...; 1 ■ ■ • ; ' • ■ ■ ■ v.;;.-- • • -x ,/./• • v.;; .v /; ?: ; ' ' J " ' ' ^ 

# cd /usr/sunpro 

k • : J 


3. Save the files that will be overwritten, as follows: 


f ; : ; .] ... x:. . -.V-: ::.\x V x. x x- : ... . . £ * !> 

# mkdir 3 . 2 

# my /lib/conpile /lib/cpp /bin/ld 3.2 


4. Install 3.4 SunPro. 


... ..... ... ^ 

# ay compile /lib/ compile 

# ay cpp /lib/cpp 

# my Id /bin/ld 

# ay sake /bin/make 

# mv m4 /usr/bin/m4 

k. ............................... j 


5. Then, do the following to move the SunPro files into their appropriate directories: 


. _ '""" ■ 1 11 11 ■< 

4 xnkdir /usr/include/make 

# ay default .ok /use/include/make 

# chmod 444 /usr/includa/make/default .mk 

# ay filemerge /usr/bin 


6. If the system you are installing contains manual pages, enter the following: 


# ay /ust/man/ttani/aiake . 1 3.2 

# my oake.l filemerge. 1 /usr/man/manl 


If you are installing SunPro for a heterogeneous server system, you should do the next procedure twice, once for 
each architecture type. (Sun-2 architecture type is MC68010; Sun-3 architecture is MC68020.) 

1. Bring the system down with the shutdown command. 

2. Change the working directory to the SunPro directory, as follows: 


t xxVixxxx-iVxx^ >x : ; : 'x'- ••• ix ;/ .... \ ... ... . \ 

# cd /uar . KCarch type /aunpxo 

V . j 


where arch type is either 68010 or 68020. 

3. Save the files that will be overwritten by entering: 


V ' , ./ 'V.^. vx- : : : .x; .s:- : .xf xx; : : : x . • \ • : • / . :'y : .: xxS. ' : : v ! ; -/xx x; A 

# mkdir 3.2 

f mv /pxib .MCar ch type/l±.b /cotap LI* /pah.MCarchjype/lLb/opp /pub . HCarch type/bLn/ld \ 

/u*r . Ifcarchjype /bin/ m4 /pub . MCarchjype /bin/mak* 3.2 

v ; — : : , 
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Installing Servers 

When installing your 3.2 tape set, you must load the optional networking tools and programs if you are installing 
a server. Otherwise, the server will be unable to ran the Yellow Pages, and diskless clients will be unable to 
boot. 

Changes to MAKEDEV 

After you have finished upgrading to Release 3.4 and rebooted your system, you have to make two changes to the 
file /dev/MAKEDEV. The permissions on the file are set incorrectly and must be changed. Also, the file con- 
tains an extra copy of the MAKEDEV script. Before running MAKEDEV to create device entries, you need to edit 
the script and remove the second copy. 

Follow the next instructions to make these changes; do this for both servers and clients. 

1. Become superuser. 

2. Type 



# cfcmod 755 /dav/MAKEDEV 



to change the permissions on the file from r-r~r— to -rwxr-xr-x. 

3. Edit / dev/MAKEDEV, using your preferred editor. 

4. Find the second occurence of the MAKEDEV script, which starts on Line 398 of the file. (You can use the 
“set number” command in vi to display line numbers.) 

5. Delete the text from this line to the end of the file. 

To Use CGI, You Must Load Suntools Libraries 

An unintentional dependency was added into the SunCGI library, which now requires that the Suntools library 
also be linked. Use the following libraries for the linking of SunCGI programs with this release: 
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-lcgi -lsuntool -lsunwindow -lpixrect -lm 

If -lsuntool is not included in the loading phase of the program, the loader will flag an undefined reference to 
“window_get” This routine is only referenced when you use SunCGI in conjunction with canvases. 

This dependency will be removed in the next release. 

Remotely Installing 3.4 on a Tapeless Server 

If you plan to do a remote installation of Release 3.4 on a tapeless server, you should run if conf ig before 
using the remote drive. Refer to the section on if conf ig in Chapter 4 of Release 3.4 Manual for the Sun 
Workstation and the if conf ig(8) manual page for more information about this command. 

Configuring Systems with High-Resolution Monochrome Monitors 

If you have a system such as a Sun-3/260, with a high resolution (1600 x 1280) monochrome monitor and one or 
more color monitors, you should configure the EEPROM so that the monochrome monitor or one of the serial 
ports is the console device. If you make a color monitor the console, the high resolution monochrome monitor 
may be unusable. 

Obtaining Pre-formatted Manual Pages 

If you want to maintain formatted manual pages on your system, you should do the following: 

1. Completely install Release 3.4 and reconfigure the kernel, as described in Chapters 2 and 3 of Release 3.4 
Manual for the Sun Workstation. 

2. Ensure that you have 8 Mbytes of available disk space. 

3. Run catman(8). catman formats the man pages and builds the what is database. 

For more information about catman(8) and whatis(l), refer to their respective man pages. 

Known Bug in Release 3.4 Software 

The following bug is known to occur in Release 3.4. It is not documented in the release manual. 

Lockscreen Bug 

The -e option to the Sun View lockscreen program is brokea This option is supposed to enable you to exit 
the SunView environment that is running lockscreen without returning to SunView. Instead, when you 
invoke the I Exit Desktop I button, the tools are destroyed but the Suntools program is not exited. Also, when run- 
ning multiple instances of Suntools on different screens, invoking I Exit Desktop 1 crashes the kernel. 

Known Bug in Release 3.4 Manual 

The following bug was reported as fixed in Release 3.4 Manual for the Sun Workstation , but actually has not been 
fixed. 

Problems with Textedit 

Textedit still incorrectly sizes windows when you use the -Ww flag. 

Additions and Changes to the Release 3.4 Manual 

The following updates were made to the release software after the Release 3.4 Manual for the Sun Workstation was 
printed. 
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Additions to Chapter 6, Bug Fixes Since Release 3.3 
Language-Related Bug Fixes 

Incorrect Evaluation of Bit Fields 

In Release 3.2, cc incorrectly evaluated a bit field compared against an integer constant with the value of 0. This 
has been fixed in Release 3.4. 

C Compiler Lost Track of Register Variables 

The C compiler sometimes lost track of register variables after function calls. For example, if you declared a pro- 
gram register variable a and assigned it to a register, and then, in another function, declared another register vari- 
able b, the compiler would incorrectly assign b to the same register. The value of a would then be lost. This 
problem has been fixed in Release 3.4. 

SunView Bug Fixes 

TEXTSW_INSERTI0N_P0INT Takes Effect Immediately 

In previous releases, if you set the TEXTS W_INSERTI0N_P0INT attribute, the caret did not display in the 
new location until the user moved the mouse cursor out of, then back into the text subwindow. The caret now 
jumps to the new position immediately (though, as before, if the new location is not in the window the caret will 
not be visible unless you call textsw_j?ossibly_norinalize ( ) ). 

cmdtool Handles Child’s Exit Correctly 

In Release 3.2, if you ‘Quit’ a cmdtool while still running a program from its shell (for example, listing a long 
file using cat), the program would still be running. If you then started a new cmdtool , if the new cmdtool 
happened to use the same pty as the previous one you ‘Quit,’ then the new cmdtool would get a SIGHUP sig- 
nal from the previous shell and it would exit. Now when you ‘Quit’ from cmdtool, the cmdtool sends a 
SIGHUP signal to make the child exit, so a new invocation of cmdtool should not encounter the previous 
cmdtool ’s children. 

Notes for the 3.2 FCS Release 

Sysdiag and the EEPROM 

If you use sysdiag to test the FPA and the 68881, it may be necessary to alter the EEPROM to ensure that the 
68881 is configured in the EEPROM. See Installing Unix on the Sun Workstation for details on EEPROM pro- 
gramming. 

Source to SunView Examples Is Available 

The source for most of the programs in the “Example Programs” appendix to the Release 3.2 SunView 
Programmer’s Guide (800-1345) is available in /usr/src/sun/suntool/examples. The source to 
seln_demo, a sophisticated selection monitor from the SunView System Programmer’ s Guide (800-1342), is 
also included. This directory is installed along with source for some of the SunView programs and demos if you 
select SunView and Demo Program source from Setup’s Optional Software form. (If you are upgrading to 3.2, 
answer y to install Suntools_source.) Some of the examples are slightly improved from the versions in the 
manual. 

Subwindow Layout Policy Changed 

In Release 3.0, when a frame was made smaller, either by stretching the frame down or from a call to 
window_set(), a bug sometimes caused the frame border to not be drawn. 
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In Release 3.2 and subsequent releases, the window layout management software now tries to preserve the frame 
border by resizing subwindows when the frame’s size is changed. That is, when a frame is made smaller, 
subwindows that cross the frame border are resized to fit within the frame. When a frame is enlarged, subwin- 
dows that are smaller than their requested size are resized (up to their requested size) to meet the frame border. 
Here “requested size” is the subwindow’s initial size, or the size the subwindow was altered to. 

This bug fix restores the behavior of Release 2.0 SunWindows. 

Games 

The following games and associated files are no longer supplied: 

battlestar 

ching 

craps 

moo 

monop 

quiz 

rain 

robots 

sail 

sail . log 

snake 

snscore 

trek 

worm 

worms 

lib/battlestar . log 
lib/ching.d 
lib/quiz .k 
lib/robots roll 



Known Bugs in Release 3.2 

Disk Errors on Sun-3/200 Series Workstations 

Disk errors of the following form may occur occasionally: 

PHI l ' ... |||pp 1 y ; ; >x.x : . • . . . . , . ; •• • . , . 7. : . : : j. V.;;:/ ^ 

xy disk partition : read [write retry (message) 

- blk #number, abs blk #nuirtber 

< - 

In general, these errors are not fatal. The message is usually one of the following: 
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III disk sequencer error 

cylinder 5 head header error 
memory addr error 
header not found 
. double hard error 

yg ; l:-, A ::;'-.- iil a ' • ■ ■ - ■"••••• . : ai — ___i ±1 • - , v :; — J 

For example: 



gtfilifniilpHI addr' error) >- blk #19:3038, abs blk #242618 



Sun-2 Abort Sequence Bug 

If you abort the boot sequence on a Sun-2/1 00 or 120, attempting to boot from tape may result in the output of a 
long series of capital Y’s until the boot is again aborted. The workaround is to enter kl at the boot PROM 
prompt ( > ). 

This bug seems to result from the keyboard UART being left in an improper state and therefore will not be seen 
on machines using terminals rather than Sun monitors/keyboards. 

VME-to-VME Adapters in a Sun -3/1 10 

When a VME-to-VME adapter (Sim Option 160A) is used to install non-Sun hardware into a Sun-3/110, the 
adapter must have a part number of 501-1 191-01 or higher. If the adapter is Sun part number 501-1059-01 or 
earlier version of Sun Option 160A, you may not be able to boot the system to 501-1191-01. 

The Sun VME SCSI Controller that is mounted in the VME-to-VME adapter must be 501-1138-01 or higher. An 
earlier version of the Sun VME SCSI Controller (part number 501-1149-01 or higher) used in other Sun products 
(Sun-2/130/160 and Sun-3/160/180) will cause the system to not boot. 

Formatting SMD Disks 

The format command now reads the defect list and is therefore recommended instead of the fix command. 

Installing a File Server as a Remote Host 

If you plan to use the file server you are installing as a remote host for remote installation of another workstation, 
you will need an additional 5 Mbytes of free space in one of your file systems, for example, /pub. 

Booting from SMD disks 

When booting mini-UNIX on a VME-based workstation from a Xylogics disk controller jumpered for 20-bit 
addressing, the kernel may panic with the following error: 

< 1 ‘ 1 
unable to mount root 

k _ _ : _ — ___ _ _ , . ■ - _ __ , ' _ • — • • : : ^ -- ^ : 



This happens when booting for the first time. When booted a second time (without reloading mini-UNIX), the 
workstation should boot without any problems. 

Normally pins JM on the controller are jumpered for 24-bit addressing. 
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Setup Client Cards 

Setup does not have client cards for Sun models 2/100, 3/1 10, and 3/2x0. Use the 2/120 card for the 2/100, and 
one of the 3/160 cards for the 3/1 10 and 3/2x0 series. 

Note that the cards for the color workstations default to a 24-megabyte swap area. 

Using vtlOO Consoles 

Using terminal type “vtlOO” during Setup will result in a core dump. Use terminal type “ansi.” 

Using echo -n in Bourne Shell Scripts 



If you specify System V behavior (for example, PATH=/usr/5bin : $PATH), shell scripts that contain lines 
such as 




with a trailing newline. Specify a path without /usr / 5bin to get the 4.2BSD behavior. 



Additions and Changes to Release 3.2 and Later Documents 

The following are updates to Release 3.2 documentation. 

Languages Documentation 
Partial Optimization 

Page 4 of the Floating-Point Programmer’s Guide (800-1552-01) refers to partial optimization as -p. Change 
this to -P, because lowercase p is used to specify profiling. 

CPU Board Level 

The FPA is intended to be used with CPU’s with part numbers 501-1163 or 501-1164. You can use 
mc68881version(8) to test die CPU board level. If the 68881 is described as “A79J,” the CPU board was not 
properly updated prior to the installation of the FPA. 

Graphics Documentation 

GP Example Source 

The Software Interface Manual for the Sun Graphics Processor includes example applications for the GP. They 
are described in Appendix A of that manual. Machine-readable code is included in /usr / src/ sun/ demo /GP 
1 / VIEWPORT. There are two errors in the source files for this package. 

In box . c, the routine init_gp should use the gpl_d function instead of ioct 1 ’s to get the minor device 
number and the static block. 
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Change 

GP_fd = gpl_d(pw->pw_pixrect) ”>ioctl_fd; 

if ( (ioctl(GP_fd, GP1I0J3ET_STATIC_BL0CK, &GP_statblk) « 0) || 

(ioctl (GP__fd r GP 1 IO_GET__TRUMINORDEV f &GP_mindev) « 0)) 

{ 

perror ("") ; 
exit (0) ; 

1 

to 

GP_fd = gpl_d(pw->pw_clipdata->pwcd_jprmulti) ->ioctl_fd; 
GP__mindev = gpl__d (pw->pw_clipdata->pwcd_j>rmulti) ->minordev; 
if ( (GP__statblk = gpl_get_static_block (GP_fd) ) « 0) 

{ 

fprintf (stderr f "Cannot get static blockO) ; 
exit ( 0 ) ; 

} 



In gpbuf . c, the gpb pointer is accessed before it has been initialized. 
Move the lines 




gpb->gpb_gfd = gpl__d (pw->pw__clipdata->pwcd_prmulti) ->ioctl__fd; 
gpb->gpb_mindev = gpl_d (pw->pw_clipdata->pwcd_jprmulti) ->minordev; 
if ( (gpb->gpb_sbindex = gpl__get_static_block (gpb->gpb_gfd) ) « 0) 
error ("Create_VP : cannot acquire GP static blockO, 0, 0) ; 



so they appear after the statement 




Sun Workstation is a registered trademark of Sun Microsystems, Inc. 
t UNIX is a trademark of AT&T Bell Laboratories. 
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CLEAR ( 1 ) 



USER COMMANDS 



CLEAR ( 1 ) 



NAME 

clear - clear screen 

SYNOPSIS 

clear 

DESCRIPTION 

Clear clears your screen if this is possible. It looks in the environment for the terminal type and then in 
letcltermcap to figure out how to clear the screen. 

FILES 

/etc/termcap terminal capability data base 
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CLE ARCOLORMAP ( 1 ) 
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CLE ARCOLORMAP ( 1 ) 



NAME 

clearcolormap - make console text visible 
SYNOPSIS 

clear colormap [ -no ] [ -f framebuffer ] 

DESCRIPTION 

Clear colormap ensures that text displayed on the console is visible. If no options are specified it clears 
the frame buffer and initializes the first two colormap entries. If the frame buffer has an overlay plane it is 
also cleared and the overlay enable plane is set so that the entire overlay plane is displayed. 

OPTIONS 

-n Do not clear the frame buffer or overlay plane. 

-o Do not clear the overlay plane or modify the overlay enable plane. 

-f framebuffer 

Operate on frame buffer device framebuffer instead of the default, /dev/fb. 
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Compression: xxjcx% 

Percentage of the input saved by compression. (Relevant only for -v.) 

- not a regular file: unchanged 

When the input file is not a regular file, (e.g. a directory), it is left unaltered. 

— has xx other links: unchanged 

The input file has links; it is left unchanged. See /«( 1) for more information. 

-- file unchanged 

No savings are achieved by compression. The input remains uncompressed. 

SEE ALSO 

A Technique for High Performance Data Compression , Terry A. Welch, IEEE Computer, vol. 17, no. 6 
(June 1984), pp. 8-19. 

compact(l), pack(l) 

BUGS 

Although compressed files are compatible between machines with large memory, -bl2 should be used for 
file transfer to architectures with a small process data space (64KB or less). 

compress should be more flexible about the existence of the X suffix. 
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CP(1) 



USER COMMANDS 



CP(1) 



NAME 

cp - copy files 

SYNOPSIS 

cp [ — i ] [ — p ] [ — rR ] filel file2 
cp [ — i ] [ — p ] [ -rR ] file . .. directory 

DESCRIPTION 

Filel is copied onto file2 . The mode and owner of file2 are preserved if it already existed; the mode of the 
source file is used otherwise. 

In the second form, one or more files are copied into the directory with their original file-names. 

Cp refuses to copy a file onto itself. 

OPTIONS 

-i Interactive: prompt the user with the name of the file whenever the copy would overwrite an old 
file. Answering with ’y’ means that cp should go ahead and copy the file. Any other answer will 
prevent cp from overwriting the file. 

-p Preserve: attempt to preserve (duplicate) in its copies the modification times and modes of the 
source files, ignoring the present umask . 

-r 

-R Recursive: if any of the source files are directories, cp copies each subtree rooted at that name; in 
this case the destination must be a directory. In the case of a symbolic link, the link itself is not 
replicated. Instead, cp duplicates the contents of the file pointed to by the symbolic link. 

EXAMPLES 

To make a backup copy of goodies : 

% cp goodies old.goodies 
To copy an entire directory hierarchy: 

% cp -r /usr/wendy/src /usr/wendy/backup 
However, BEWARE of a recursive copy like this one: 

% cp -r /usr/wendy/src /usr/wendy/src/backup 
which keeps copying files until it fills the entire file system. 

SEE ALSO 

cat(l), pr(l), mv(l), rcp(lC) 

BUGS 

There should be an option to copy timestamps to the new files — for instance, when copying a whole 
hierarchy from one file system to another file system, or when making a backup copy. 
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DD( 1 ) 



To read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into the ASCII file x: 
tutorial% dd if=/dev/rmtO of=x ibs=800 cbs=80 con v=ascii, lease 

Note the use of raw magtape: dd is especially suited to I/O on the raw physical devices because it allows 
reading and writing in arbitrary record sizes. 

SEE ALSO 

cp(l), tr(lV) 

DIAGNOSTICS 

f+p records in(out): numbers of full and partial records read( written) 

BUGS 

The ASCII/EBCDIC conversion tables are taken from the 256 character standard in the CACM Nov, 1968. 
The ibm conversion, while less blessed as a standard, corresponds better to certain IBM print train conven- 
tions. There is no universal solution. 

The block and unblock options cannot be combined with the ascii, ebcdic or ibm. Invalid combinations 
silently ignore all but the last mutually-exclusive keyword. 
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DEFAULTSEDIT ( 1 ) 



USER COMMANDS 



DEFAULTSEDIT ( 1 ) 



NAME 

defaultsedit, defaults_merge, defaultsfrominput defaults_to_indentpro, defaultstomailrc, 
indentprotodefaults, lockscreendefault, mailrc_to_defaults, scrolldefaults - window- and mouse-based 
default parameters editor 

SYNOPSIS 

defaultsedit 

DESCRIPTION 

defaultsedit is a standard tool provided with the SunView environment. 

defaultsedit presents a convenient user interface for inspecting and setting default parameters. It can be 
viewed as a replacement for the traditional UNIX defaultsedit to manipulate options to the programs 
indent, mail and mailtool, stty, and defaultsedit, as well as the menu, scrollbar, text subwindow and tty 
subwindow packages and the SunView environment. 

Any program or package which a user can customize by setting or changing a parameter could be written 
such that it gets its options from the database manipulated through defaultsedit. For information on how to 
do this see the chapter on the Defaults Database in the SunView System Programmer’s Guide. 

OPTIONS 

defaultsedit accepts all of the generic tool arguments discussed in suntools(l). 

SUB WINDOWS 

defaultsedit consists of four subwindows. From top to bottom they are: 

control contains the name of the categoiy currently displayed, and buttons labeled SAVE, QUIT, 
RESET, and EDIT ITEM. To change the category, click on the word CATEGORY with the 
left mouse button, or use the menu that pops up when you click with the right mouse button. 

message a small text subwindow where messages from defaultsedit are displayed. 

parameters shows all current default parameter names with corresponding values. Clicking the left 
mouse button over a parameter displays a help string in the message subwindow. 

edit a small text subwindow which enables text editing of parameter values. This is useful for 

very long text values, such as a long mailing list 

USING DEFAULTSEDIT 

SAVE Saves the current values for all categories in your private database — that is, the .defaults 

file in your home directory. 

QUIT exits without saving any changes. 

RESET resets the default parameters of the current categoiy to the values in your private database. 

This is useful if you change some values, then change your mind and want to restore the ori- 
ginal values. 

EDIT ITEM Pressing the right mouse button over the EDIT ITEM button brings up a menu with three 
choices: COPY ITEM, DELETE ITEM and EDIT LABEL. Only text or numeric items can 
be edited. Also, note that edits made using this menu will appear only in your private 
defaults database, not in the master database. The three editing operations are described 
below. 

COPY ITEM Selecting COPY ITEM causes the current item to be duplicated. You can then edit both the 
label and the value of the the newly created item. Only items with text or numeric values 
can be copied in this way. COPY ITEM is useful when you want to change the number of 
instances of a certain type of item — for example, to insert a new mail alias into your 
defaults database. 

DELETE ITEM 

Selecting DELETE ITEM will delete the current item from your private database. It cannot 
be permanently deleted if the corresponding node is present in the master database. 
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However, you can make it behave like an undefined node by giving it die special value 
\255UndefineA255. 

EDIT LABEL 

Selecting EDIT LABEL allows you to edit the label of the current item. When you select 
EDIT LABEL, the label of the current item changes from bold to normal face. Then you 
can select the label and edit it as a normal panel text item. 

ENVIRONMENT 

DEFAULTS_FILE 

The value of this environment variable indicates the file from which SunView defaults 
are read. When it is undefined, defaults are read from the .defaults file in your home 
directory. 

FILES 

'/.defaults /usr/lib/ defaults/*. d 

Note: A performance optimzation may be enabled by setting the Private only parameter in the Defaults 
category. If this is set to True, only the user’s private defaults file is consulted. 

SEE ALSO 

Windows and Window-Based Tools: Beginner’ s Guide 
The SunView System Programmer’ s Guide 

BUGS 

Editing of choice items or categories is not supported by defaultsedit. Neither is editing of the master 
defaults database — to add a new program to the master defaults database, you have to edit a master 
defaults textfile. 

Switching between certain categories may cause the database to be reread and over-write any changed 
values. Therefore, using the "Save" button for each category changed is recommended. 
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NAME 

delta - make a delta (change) to an SCCS file 
SYNOPSIS 

/usr/sccs/delta [— r SID ] [ — s ] f — n ) [ — g list \ [ -m [ mrlist ] ] [— y [comment] ] [ — p ] file ... 
DESCRIPTION 

Delta permanently introduces into the named SCCS file changes that were made to the file retrieved by 
get{ 1) (called the g-file, or generated file). 

Delta makes a delta to each named SCCS file. If a directory is named, delta behaves as though each file in 
the directory were specified as a named file, except that non-SCCS files (last component of the path name 
does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input 
is read (see WARNINGS ); each line of the standard input is taken to be the name of an SCCS file to be pro- 
cessed. 

Delta may issue prompts on the standard output depending upon certain options specified and flags (see 
admin ( 1)) that may be present in the SCCS file (see -m and -y options below). 

OPTIONS 

Options apply independently to each named file. 

-r SID Uniquely identifies which delta is to be made to the SCCS file. The use of this option is necessary 
only if two or more outstanding get’s for editing (get -e) on the same SCCS file were done by the 
same person (login name). The SID value specified with the -r option can be either the SID 
specified on the get command line or the SID to be made as reported by the get command (see 
get( 1)). A diagnostic results if the specified SID is ambiguous, or, if necessary and omitted on the 
command line. 

-s Do not display the created delta’s SID, number of lines inserted, deleted and unchanged in the 
SCCS file. 

-n Retain the edited g-file which is normally removed at completion of delta processing. 

-g list Specifies a list of deltas to be ignored when the file is accessed at the change level (SID) created 
by this delta. See get( 1) for the definition of list. 

—m [mrlist] 

If the SCCS file has the v flag set (see admin ( 1)), a Modification Request (MR) number must be 
supplied as the reason for creating the new delta. 

If -m is not used and the standard input is a terminal, the prompt MRs? is issued on the standard 
output before the standard input is read; if the standard input is not a terminal, no prompt is issued. 
The MRs? prompt always precedes the comments? prompt (see -y option). 

MRs in a list are separated by blanks and/or tab characters. An unescaped new-line character ter- 
minates the MR list 

Note that if the v flag has a value (see admin( 1)), it is taken to be the name of a program (or shell 
procedure) which will validate the correctness of the MR numbers. If a non-zero exit status is 
returned from MR number validation program, delta terminates (it is assumed that the MR 
numbers were not all valid). 

-y [comment] 

Arbitrary text to describe the reason for making the delta A null string is considered a valid com- 
ment. 

If-y is not specified and the standard input is a terminal, the prompt comments? is issued on the 
standard output before the standard input is read; if the standard input is not a terminal, no prompt 
is issued. An unescaped new-line character terminates the comment text 

-p Display (on the standard output) the SCCS file differences before and after the delta is applied in a 
diff{\) format 
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Error messages that can be intuited are candidates for insertion into the file to which they refer. 

Only true error messages are inserted into source files. Other error messages are consumed entirely by 
error or are written to the standard output. Error inserts the error messages into the source file on the line 
preceeding the line number in the error message. Each error message is turned into a one line comment for 
the language, and is internally flagged with the string ‘###’ at the beginning of the error, and ‘%%%’ at the 
end of the error. This makes pattern searching for errors easier with an editor, and allows the messages to 
be easily removed. In addition, each error message contains the source line number for the line the mes- 
sage refers to. A reasonably formatted source program can be recompiled with the error messages still in 
it, without having the error messages themselves cause future errors. For poorly formatted source pro- 
grams in free format languages, such as C or Pascal, it is possible to insert a comment into another com- 
ment, which can wreak havoc with a future compilation. To avoid this, format the source program so there 
are no language statements on the same line as the end of a comment. 

OPTIONS 

-n Do not touch any files; all error messages are sent to the standard output 

-q Error asks whether the file should be touched. A ‘y’ or c n’ to the question is necessary to continue. 
Absence of the — q option implies that all referenced files (except those refering to discarded error 
messages) are to be touched. 

-v After all files have been touched, overlay the visual editor vi with it set up to edit all files touched, 
and positioned in the first touched file at the first error. If vi can’t be found, try ex cm* ed from stan- 
dard places. 

-t Take the following argument as a suffix list. Files whose suffices do not appear in the suffix list are 
not touched. The suffix list is dot seperated, and wildcards work. Thus the suffix list: 

".c.y.fr.h" 

allows error to touch files ending with ‘.c’, \y\ ‘.f*’ and ‘.h’. 

-s Print out statistics regarding the error categorization. Not too useful. 

Error catches interrupt and terminate signals, and if in the insertion phase, will orderly terminate what it is 
doing. 

FILES 

7.errorrc 
/dev/tty 

BUGS 

Opens the teletype directly to do user querying. 

Source files with links make a new copy of the file with only one link to it. 

Changing a language processor’s format of error messages may cause error to not understand the error 
message. 

Error , since it is purely mechanical, will not filter out subsequent errors caused by ‘floodgating’ initiated 
by one syntactically trivial error. Humans are still much better at discarding these related errors. 

Pascal error messages belong after the lines affected (error puts them before). The alignment of the ‘ |’ 
marking the point of error is also disturbed by error. 

Error was designed for work on CRT’s at reasonably high speed. It is less pleasant on slow speed termi- 
nals, and has never been used on hardcopy terminals. 



function names to ignore for lint error messages 
user’s teletype 
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NAME 

ex, edit, e - text editor 
SYNOPSIS 

ex [-] [-R] [ — r ] [ — t tag ] [+command] [-v] [-x] [ -wnnn ] [-l]//e ... 
edit [ options ] 

DESCRIPTION 

ex, a line editor, is the root of a family of editors that includes edit, ex, and vi (the display editor). In most 
cases vi is preferred for interactive use. 

OPTIONS 

- supress all interactive feedback to the user — useful for processing ex scripts in shell files. 

-R Readonly. Do not overwrite the original file. 

-r recover the indicated files after a system crash. 

-t tag edit the file containing the tag tag . A tags database must first be created using the cfags(l) com- 
mand. 

^command 

start the editing session by executing command. 

-v start up in display editing state using vi'(l). You can achieve the same effect by simply typing the 
vi command itself. 

-x prompt for a key to be used in encrypting the file being edited. 

-wnnn set the default window (number of lines on your terminal) to nnn — this is useful if you are dial- 
ling into the system over a slow ’phone line. 

-1 set up for editing LISP programs. 

ENVIRONMENT 

The editor recognizes the environment variable EXINIT as a command (or list of commands separated by | 
characters) to run when it starts up. If this variable is undefined, the editor checks for startup commands in 
the file l.exrc file, which you must own. However, if there is a .exrc owned by you in the current direc- 
tory, the editor takes its startup commands from this file — overriding both the file in your home directory 
and the environment variable. 



FILES 

/usr/lib/ex?.?strings 

/usr/lib/ex?.?recover 

/usr/lib/ex?.?preserve 

/etc/termcap 



error messages 

recover command 

preserve command 

describes capabilities of terminals 
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NAME 

filemerge - window-based file comparison and merging program 
SYNOPSIS 

filemerge [ — r ] [ — b ] [ — I listfile ] [ -a ancestor ] [ leftfile [ rightfile [ outfile ] ] ] 

DESCRIPTION 

Filemerge is a window-based version of diff( 1), for comparing and merging text files. It displays two files 
for side-by-side comparison, each in a read-only text-subwindow. Beneath them, an editing subwindow 
can be used to construct a merged version — one which contains selected lines from either or both input 
files, along with any additional edits you may make. 

leftfile and rightfile are the files to be compared, and outfile is name of the file containing the merged ver- 
sion. If outfile is a directory, then the output is placed in the file outfile! leftfile. If outfile is omitted, the 
output file is named filemerge.out by default. If no filename arguments are given, you can enter them from 
within the tool itself. 

OPTIONS 

— r Readonly mode. Don’t display the editing subwindow. 

— b Ignore leading blanks in comparisons. 

—a ancestor 

Compare both files with respect to ancestor . A minus-sign indicates lines that have been deleted 
relative to the ancestor. A plus-sign indicates lines added relative to the ancestor. 

—1 listfile 

Process a list of filename pairs. With this option, leftfile and rightfile are the names of directories, 
and listfile contains a list of filenames that appear in both, filemerge compares the versions of 
each file between the two directories, and allows you to create a merged version (typically in the 
directory outifile). The SHIFT-Load command button, which is selected by holding the SHIFT 
key while clicking on the Load button, reads in the next pair named in the list If listfile is -, then 
the list of files is read from the standard input 

USAGE 

The text in the editing sub window ( outfile ) is initially the same as that in leftfile. To construct a merged 
version, you can directly edit the text of outfile with textedit commands, or you can change a selected 
difference to match rightfile (the one on the right) by clicking the Right button in the top panel. 

Differences 

At any given time, one of the displayed “differences” is current. The current difference is indicated by 
emboldening the symbol adjacent to each line, and also by the notation “i of n ” displayed in the control 
panel. Once a difference is current, you can use the Left and Right buttons to apply either the left-hand or 
the right-hand version of the text to outfile. The Next and Prev buttons select the next or previous differ- 
ence, respectively. 

Property Sheet 

You can customize filemerge using the property sheet to set or alter various display and control options. 
To bring up the property sheet, press the Props function key (typically L3) while the mouse is over any 
part of filemerge. 

Menus 

There are pop-up menus associated with several of the control panel items, and a menu associated with the 
editing subwindow. The former provide to select any command function obtained with a modified mouse- 
button (such as SHIFT-Next); the editing subwindow’s menu has items that control the filename and direc- 
tory location of the merged output To bring up a menu, move the mouse-cursor to the command button, or 
to the editing subwindow, and hold down the right mouse-button. Select a desired menu item by releasing 
the mouse-button after moving the cursor on top of it 
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Command Buttons 

Next Make the next difference current The subwindow scrolls, if necessary, to display it 

SHIFT -Next Make the first difference current. (Also a menu item from the Next menu.) 

Prev Make the previous difference current 

SHIFT-Prev Make the last difference current (Also a menu item from the Prev menu.) 

Right Apply right-hand version of the current difference to outfile. If autoadvance is in effect 

advance to the next difference. 

SHIFT-Right Apply the right-hand version and advance to the next difference, unless autoadvance is in 
effect (Also a menu item from the Right menu.) 

CTRL-Right Apply the right-hand version for the current difference, and for all subsequent differences 
up to die end of the file. 

Left Apply the left-hand version of the current difference. 

Undo Undo the last Right or Left operation. You can undo up to 100 stacked operations. You 

can’t undo an undo. 

SHIFT-Undo Undo all the operations since the last Load, or the last 100 operations. 

Scroll-Lock When in effect, the three text-subwindows scroll in unison. Otherwise each subwindow 
scrolls independently. 

i of n The number of the current difference, i, out of n detected differences. Popping up a menu 

on this item allows you to jump to a selected difference. 

Load Load the files whose names appear by the prompts Filel: and File2:. 

SHIFT-Load When the -1 option is used, load the files from the directories shown in Filel and File2 
corresponding to the next name in the list (taken from the listfile argument). 

Done Save outfile and close the tool. The name used to save the file appears in the namestripe, in 

the same fashion as textedit. 

SHIFT-Done Save without closing. You can also save the merged version using the Save item in the edit- 
ing subwindow’s menu. 

Quit Exit the tool. You must explictly save your merged outfile, either with the Done button or 

the Save item in the editing subwindow’s menu. 

Properties 

Hitting the L3 function key brings up a property sheet that controls several filemerge parameters. The 
information in the property sheet is stored in the file 7 filemergerc . The property panel items have the fol- 
lowing meanings: 

Apply Any changes you have made to the property sheet will now take effect 

Reset reset the property sheet to the state it had at the time of the last Apply. 

Done Close the property sheet 

autoadvance Advance to the next difference after each Left or Right operation. 

T oplines number of lines in the top two sub windows 

Bottomlines number of lines in the bottom subwindow 

Columns number of columns in the left (and also right) subwindow 

FILES 

7.filemergerc file storing property sheet information 
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SEE ALSO 

diff (1), sdiffW, textedit(l) 

BUGS 

Using the Find function key causes the subwindows to get out of sync for scrolling. To resync them, turn 
Scroll-Lock first off, and then on. 
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NAME 

grep, egrep, fgrep - search a file for a pattern 
SYNOPSIS 

grep [ — v ] [ — c ][—!][ — n ] [ — b ][—■][ — s ] [ — bi ] [-w] [-*) expression [file ...] 

egrep [ -v ] [ -c ] [ -I ] [ -n ] [ -b ] [ -i ] [ -s ] [ -h ] [ -e expression ] [ -f file ] 

[ expression ] [file . . . ] 

fgrep [ —v ] t-x] [ — c ] [-1] [-n] [ — b ] [ — i ] [ — s ] [-h] 

[ -e string ] [ —ffile ] [ string ] [file . . . ] 

SYSTEM V SYNOPSIS 

grep [ -v ] [ -c ] [ -1 ] [ -n ] [ -b ] [ -i ] [ -s ] expression [file ...] 

DESCRIPTION 

Commands of the grep family search the input file s (standard input default) for lines matching a pattern. 
Normally, each line found is copied to the standard output Grep patterns are limited regular expressions in 
the style of ed( 1). Egrep patterns are full regular expressions including alternation. Fgrep patterns are 
fixed strings — no regular expression metacharacters are supported. 

In general, egrep is the fastest of these programs. 

Take care when using the characters $,*,[, \ | , (, ), and \ in the expression, as these characters are also 
meaningfiil to the Shell. It is safest to enclose the entire expression argument in single quotes 

When any of the grep utilities is applied to more than one input file, the name of the file is displayed 
preceding each line which matches the pattern. The filename is not displayed when processing a single file, 
so if you actually want the filename to appear, use /dev/null as a second file in the list 

OPTIONS 

-v Invert the search to only display lines that do not match. 

-x Display only those lines which match exacdy — that is, only lines which match in their entirety 
( fgrep only). 

-c Display a count of matching lines rather than displaying the lines which match. 

-1 List only the names of files with matching lines (once) separated by newlines. 

-n Precede each line by its relative line number in the file. 

-b Precede each line by the block number on which it was found. This is sometimes useful in locat- 

ing disk block numbers by context 

-i Ignore the case of letters in making comparisons — that is, upper and lower case are considered 
identical. 

-s Work silently, that is, display nothing except error messages. This is useful for checking the error 
status. 

-h Do not display filenames. 

-w search for the expression as a word as if surrounded by \< and \>. grep only. 

-e expression 

Same as a simple expression argument but useful when the expression begins with a — . 

-f file Take the regular expression (egrep) or a list of strings separated by newlines (fgrep ) from file. 

SYSTEM V OPTIONS 

The System V version of grep does not recognize the -h, -w, or -e options. The -s option indicates that 
error messages for nonexistent or unreadable files should be suppressed, not that all messages should be 
suppressed. 
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REGULAR EXPRESSIONS 

The following one-character regular expressions match a single character 

c An ordinary character (not one of the special characters discussed below) is a one-character regu- 
lar expression that matches that character. 

\c A backslash (\) followed by any special character is a one-character regular expression that 
matches the special character itself. The special characters are: 

a. ., *, [, and \ (period, asterisk, left square bracket, and backslash, respectively), which are 
always special, except when they appear within square brackets ([ ]). 

b. * (caret or circumflex), which is special at the beginning of an entire regular expression, or 
when it immediately follows the left of a pair of square brackets ([ ]). 

c. $ (currency symbol), which is special at the end of an entire regular expression. 

. A period (.) is a one-character regular expression that matches any character except newline. 

[string] 

A non-empty string of characters enclosed in square brackets is a one-character regular expression 
that matches any one character in that string. If, however, the first character of the string is a 
circumflex (*)> the one-character tegular expression matches any character except newline and the 
remaining characters in the string. The A has this special meaning only if it occurs first in the 
string. The minus (-) may be used to indicate a range of consecutive ASCII characters; for exam- 
ple, [ 0 - 9 ] is equivalent to [ 0123456789 ]. The - loses this special meaning if it occurs first (after 
an initial \ if any) or last in the string. The right square bracket (]) does not terminate such a 
string when it is the first character within it (after an initial \ if any); e.g., [ ]a— f] matches either a 
right square bracket (]) or one of the letters a through f inclusive. The four characters ., *, [, and \ 
stand for themselves within such a string of characters. 

The following rules may be used to construct regular expressions: 

* A one-character regular expression followed by an asterisk (*) is a regular expression that 
matches zero or more occurrences of the one-character regular expression. If there is any choice, 
the longest leftmost string that permits a match is chosen. 

\( A regular expression enclosed between the character sequences \( and \) matches whatever the 
unadorned regular expression matches, (grep only). 

\n The expression Vi matches the same string of characters as was matched by an expression 
enclosed between \( and \) earlier in the same regular expression. Here n is a digit; the sub- 
expression specified is that beginning with the n-th occurrence of \( counting from the left For 
example, the expression A \(.*\)\l$ matches a line consisting of two repeated appearances of the 
same string. 

concatenation 

The concatenation of regular expressions is a regular expression that matches the concatenation of 
the strings matched by each component of the regular expression. 

The sequence \< in a regular expression constrains the one-character regular expression immedi- 
ately following it only to match something at the beginning of a “word”; that is, either at the 
beginning of a line, or just before a letter, digit, or underline and after a character not one of these. 

The sequence \> in a regular expression constrains the one-character regular expression immedi- 
ately following it only to match something at the end of a “word”; that is, either at the end of a 
line, or just before a character which is neither a letter, digit, nor underline. 

A circumflex ( A ) at the beginning of an entire regular expression constrains that regular expression 
to match an initial segment of a line. 

A currency symbol ($) at the end of an entire regular expression constrains that regular expression 
to match a final segment of a line. 
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The construction * entire regular expression% constrains the entire regular expression to match the entire 
line. 

egrep accepts regular expressions of the same sort grep does, except for \(, \), Vi, \<, and \>, with the addi- 
tion of: 

* A regular expression (not just a one-character regular expression) followed by an asterisk (*) is a 
regular expression that matches zero or more occurrences of the one-character regular expression. 
If there is any choice, the longest leftmost string that permits a match is chosen. 

+ A regular expression followed by a plus sign (+) is a regular expression that matches one or more 
occurrences of the one-character regular expression. If there is any choice, the longest leftmost 
string that permits a match is chosen. 

? A regular expression followed by a question mark (?) is a regular expression that matches zero or 

one occurrences of the one-character regular expression. If there is any choice, the longest left- 
most string that permits a match is chosen. 

| Alternation: two regular expressions separated by | or newline match either a match for the first or 

a match for the second. 

() A regular expression enclosed in parentheses matches a match for the regular expression. 

The order of precedence of operators at the same parenthesis level is [ ] (character classes), then * + ? (clo- 
sures), then concatenation, then | (alternation) and newline. 

SYSTEM V REGULAR EXPRESSIONS 

The System V version of grep does not accept \< or \> in a regular expression, and accepts the following 
additional item in a regular expression: 

\{m\} 

\{m\} 

\{m,n\} A regular expression followed by \{/n\}, \{m f \}, or \{m,n\} matches a range of occurrences of the 
regular expression. The values of m and n must be non-negative integers less than 256; \{m\} 
matches exactly m occurrences; \{m,\) matches at least m occurrences; \{m,n\] matches any 
number of occurrences between m and n inclusive. Whenever a choice exists, the regular expres- 
sion matches as many occurrences as possible. 

EXAMPLES 

Search a file for a fixed string using fgrep: 

tutorial% fgrep intro /usr/man/man3/*.3* 

Look for character classes using grep: 

tutorial% grep ’[1-8KICJMSNX])’ /usr/man/manl/*.l 
Look for alternative patterns using egrep: 

tutorials egrep ’(SallyjFred) (Smith|Jones|Parker)’ telephone.list 
To get the filename displayed when only processing a single file, use /dev/null as the second file in the list: 
tutorial% grep ’Sally Parker’ telephone.list /dev/null 

SEE ALSO 

vi(l) visual display-oriented editor based on ex(l) 

ex(l) line-oriented text editor based on ed(l) 

ed(l) primitive line-oriented text editor 

sed(l V) stream editor 

awk(i) pattern scanning and text processing language 

sh(l) Bourne Shell 

DIAGNOSTICS 

Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or inaccessible files. 

BUGS 

For ! bin! grep the order in which concatenated options appear makes a difference in the resulting output 
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Lines are limited to 1024 characters by grep ; longer lines are truncated. 

If there is a line with embedded nulls, grep will only match up to the first null; if it matches, it will print the 
entire line. 

The combination of -1 and -v options does not produce a list of files in which a regular expression is not 
found. To get such a list, use the C-Shell construct 

foreach file (*) if (‘grep "re" $file | wc -1‘ == 0) echo Sfile 

end 

Ideally there should be only one grep. 
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Fill (Button) Fill canvas with current rectangular fill pattern. 

Invert (Button) Invert each pixel represented on the canvas. 

Paintbrush 

Select from among five painting modes. Instructions for each painting mode appear above the 
canvas. The painting modes are: 

dot Paint a single dot at a time. 

line Draw a line. To draw a line on the canvas, point to the first endpoint of the line, and 
press and hold the left mouse button. While holding the button down, drag the cursor to 
the second endpoint of the line. Release the mouse button. 

rectangle 

Draw a rectangle. To draw a rectangle on the canvas, point to the first comer of the rec- 
tangle and press and hold the left mouse button. While holding the button down, drag the 
cursor to the diagonally opposite comer of the rectangle. Release the mouse button. 

In the control panel, the Fill field to the right of the rectangle indicates the current rectan- 
gle fill pattern. Any rectangles you paint on the canvas will be filled with this pattern. 

circle Draw a circle. To draw a circle on the canvas, point to the center of the circle, and press 
and hold the left mouse button. While holding the button down, drag the cursor to the 
desired edge of the circle. Release the mouse button. 

In the control panel, the Fill field to the right of the circle indicates the current circle fill 
pattern. Any circles you paint on the canvas will be filled with this pattern. 

abc Insert text. To insert text, move the painting hand to “abc” and type the desired text. 
Then move the cursor to the canvas and press and hold the left mouse button. A box will 
appear where the text is to go. Position the box as desired and release the mouse button. 

In addition, you can choose the font in which to draw the text. Point at the Fill field to 
the right of die “abc” and either click the left mouse button to cycle through the avail- 
able fonts or press and hold the right mouse button to bring up a menu of fonts. 

Load This is the rasterop to be used when loading a file in from disk. (See the Pixrect Reference 
Manual for details on rasterops). 

Fill This is the rasterop to be used when filling the canvas. The source for this operation is the rectan- 
gle fill pattern, and the destination is the canvas. 

Proof This is the rasterop to be used when rendering the proof image. The source for this operation is 
the proof image, and the destination is the proof background. 

Proof background 

The proof background can be changed to allow you to preview how the image will appear against 
a variety of patterns. The squares just above the proof area show the patterns available for use as 
the proof background pattern. To change the proof background, point at the desired pattern and 
click the left mouse button. 



SEE ALSO 

suntools(l) 

FILES 

/usr/bin/iconedit 
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NAME 

id - print user and group IDs and names 

SYNOPSIS 

/usr/5bin/id 

DESCRIPTION 

Note: Optional Software (System V Option). Refer to Installing UNIX on the Sun Workstation for infor- 

mation on how to install this command. 

id writes a message on the standard output giving the user and group IDs, and the corresponding names of 
the invoking process. If the effective and real IDs do not match, both are printed. 

SEE ALSO 

getuid(2) 
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NAME 

indent - indent and format C program source 
SYNOPSIS 

indent [ input-file [ output-file ] ] [ -bacc | -nbacc ] [ -bad | -nbad ] [ -bap | -nbap ] [ -bbb | -nbbb ] 

[ -be | -nbc ] [ -bl ] [ -br ] [ -bs | -nbs ] [ -c n ] [ -cd/i ] [ -cdb | -nedb ] [ -ce | -nee ] [ -ci/i ] 

[ -din ] [ -An ] [ -Ain ] [ -eei | -neei ] [ -fcl | -nfcl ] [ -in ] [ -ip | -nip ] [ -In ] [ -len ] 

[ -lp | -nip ] [ -pcs | -npcs ] [ -npro ] [ -psl | -npsl ] [ —sc | -nsc ] [ -sob | -nsob ] [ -st ] 

[ -troff ] [ -v | -nv ] 

DESCRIPTION 

Indent is a C program formatter. It reformats the C program in the input-file according to the switches. 
The switches which can be specified are described below. They may appear before or after the file names. 

NOTE: If you only specify an input-file , the formatting is done ‘in-place’, that is, the formatted file is writ- 
ten back into input-file and a backup copy of input-file is written in the current directory. If input-file is 
named Vblah/blah/file’, the backup file is named fil e.BAK. 

If output-file is specified, indent checks to make sure it is different from input-file . 

OPTIONS 

The options listed below control the formatting style imposed by indent . 

-bap-nbap If -bap is specified, a blank line is forced after every procedure body. Default: -nbap. 

-bacc, -nbacc If -bacc is specified, a blank line is forced around every conditional compilation block. 

ie. in front of every #ifdef and after every #endif. Other blanklines surrounding these 
will be swallowed. Default: -nbacc. 

-bad, -nbad If -bad is specified, a blank line is forced after every block of declarations. Default: 

-nbad. 

-bbb, -nbbb If -bbb is specified, a blank line is forced before every block comment. Default: 

-nbbb. 

If -be is specified, then a newline is forced after each comma in a declaration, -nbc 
turns off this option. The default is -be. 

Specifying -bl lines up compound statements like this: 
if (...) 

{ 

code 

} 

Specifying -br (the default) makes them look like this: 
if (...) { 
code 

} 

-bs,-nbs Enables (disables) the forcing of a blank after sizeof. Some people believe that sizeof 

should appear as though it were a procedure call (-nbs, the default) and some people 
believe that since sizeof is an operator, it should always be treated that way and should 
always have a blank after it. 

-c n The column in which comments on code start. The default is 33. 

-edn The column in which comments on declarations start The default is for these comments 

to start in the same column as those on code. 

-cdb,-ncdb Enables (disables) the placement of comment delimiters on blank lines. With this option 
enabled, comments look like this: 



-be, -nbc 
-br,-bl 
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/* 

* this is a comment 
*/ 

Rather than like this: 

/* this is a comment */ 

This only affects block comments, not comments to the right of code. The default is 
-cdb . 

-ce,-nce Enables (disables) forcing ‘else’s to cuddle up to the immediady proceeding *}’. The 

default is -ce . 

-ci« Sets the continuadon indent to be n. Continuadon lines will be indented that far from 

the beginning of the first line of the statement Parenthesized expressions have extra 
indentation added to indicate the nesting, unless -lp is in effect -ci defaults to the same 
value as -i. 

— clin Causes case labels to be indented n tab stops to the right of the containing switch state- 

ment -cli0.5 causes case labels to be indented half a tab stop. The default is -cliO . 

-dn Controls the placement of comments which are not to the right of code. The default -dl 

means that such comments are placed one indentation level to the left of code. Specify- 
ing -dO lines up these comments with die code. See the section on comment indentation 
below. 

-din Specifies the indentation, in character positions, from a declaration keyword to the fol- 

lowing identifier. The default is -dil6 . 

-eei-neei If -eei is specified, and extra expression indent is applied on continuation lines of the 
expression part of if() and while(). These continuation lines will be indented one extra 
level - twice instead of just once. This is to avoid the confusion between the continued 
expression and the statement that follows the if() or while(). Default: -neei. 

-fcl,-nfcl Enables (disables) the formatting of comments that start in column 1. Often, comments 
whose leading 7’ is in column 1 have been carefully hand formatted by the programmer, 
hi such cases, -nfcl should be used. The default is -fcl. 

-in The number of spaces for one indentation level. The default is 4. 

-ip,-nip Enables (disables) the indentation of parameter declarations from the left margin. The 

default is -ip . 

-In Maximum length of an output line. The default is 75. 

-lcn Sets the line length for block comments to n. It defaults to being the same as the usual 

line length as specified with -1. 

-Ip, -nip Lines up code surrounded by parenthesis in continuation lines. If a line has a left paren 

which is not closed on that line, then continuation lines will be lined up to start at the 
character position just after die left paren. For example, here is how a piece of contin- 
ued code looks with -nip in effect: 

pi = first_procedure (second_procedure (p2, p3), 
third_procedure (p4, p5) ) ; 

With -Ip in effect (the default) the code looks somewhat clearer: 

pi = first_procedure (second__procedure (p2, p3), 

third_procedure (p4, p5) ) ; 

Inserting a couple more newlines we get: 

pi = f irst_procedure (second_j?rocedure (p2, 

p3 ) , 

third_procedure (p4, 

p5 ) ) ; 
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-npro 
-pcs , — npcs 



-psl , -npsl 



-sc, -use 
-sob-nsob 



-st 

-Ttypename 



-troff 



Causes the profile files, ‘ 7.indenLpro’ and ‘7.indent.pro’, to be ignored. 

If true (-pcs) all procedure calls will have a space inserted between the name and the 
The default is -npcs 

If true (-psl) the names of procedures being defined are placed in column 1 - their types, 
if any, will be left on the previous lines. Die default is -psl 

Enables (disables) the placement of asterisks (**’s) at the left edge of all comments. 

If -sob is specified, indent will swallow optional blank lines. You can use this to get rid 
of blank lines after declarations. Default: -nsob 

Causes indent to take its input from stdin, and put its output to stdout 

Adds typename to the list of type keywords. Names accumulate: -T can be specified 
more than once. You need to specify all the typenames that appear in your program that 
are defined by typedefs - nothing will be harmed if you miss a few, but the program 
won’t be formatted as nicely as it should. This sounds like a painful thing to have to do, 
but it’s really a symptom of a problem in C: typedef causes a syntactic change in the 
laguage and indent can’t find all typedefs. 

Causes indent to format the program for processing by troff. It will produce a fancy 
listing in much the same spirit as vgrind. If the output file is not specified, the default is 
standard output, rather than formatting in place. 



The usual way to get a troff d listing is with the command 

indent -troff program.c | troff -mindent 

-v,— nv -v turns on ‘verbose’ mode, -nv turns it off. When in verbose mode, indent reports 

when it splits one line of input into two or more lines of output, and gives some size 
statistics at completion. The default is -nv. 

FURTHER DESCRIPTION 

You may set up your own ‘profile’ of defaults to indent by creating a file called dndent.pro in either your 
login directory or the current directory and including whatever switches you like. A ‘.indenLpro’ in the 
current directory takes precedence over the one in your login directory. If indent is run and a profile file 
exists, then it is read to set up the program’s defaults. Switches on the command line, though, always over- 
ride profile switches. The switches should be separated by spaces, tabs or newlines. 

Comments 

‘Box’ comments. Indent assumes that any comment with a dash or star immediately after the start of com- 
ment (that is, 7*-’ or 7**’) is a comment surrounded by a box of stars. Each line of such a comment is 
left unchanged, except that its indentation may be adjusted to account for the change in indentation of the 
first line of the comment. 

Straight text. All other comments are treated as straight text Indent fits as many words (separated by 
blanks, tabs, or newlines) on a line as possible. Blank lines break paragraphs. 

Comment indentation 

If a comment is on a line with code it is started in the ‘comment column’, which is set by the -c n command 
line parameter. Otherwise, the comment is started at n indentation levels less than where code is currently 
being placed, where n is specified by the -dn command line parameter. If the code on a line extends past 
the comment column, the comment starts further to the right, and the right margin may be automatically 
extended in extreme cases. 

Preprocessor lines 

In general, indent leaves preprocessor lines alone. The only reformmatting that it will do is to straighten up 
trailing comments. It leaves imbedded comments alone. Conditional compilation (#ifdef...#endif) is 
recognized and indent attempts to correctly compensate for the syntactic peculiarites introduced. 
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C syntax 

Indent understands a substantial amount about the syntax of C, but it has a ‘forgiving’ parser. It attempts to 
cope with the usual sorts of incomplete and misformed syntax. In particular, the use of macros like: 
♦define forever for(;;) 
is handled properly. 

FILES 

7.indent.pro profile file 

'/.indentpro profile file 

/usr/lib/tmac/tmac.indent Troff macro package for “indent -troff ’ output 

BUGS 

Indent has even more switches than Is. 

A common mistake that often causes grief is typing: 
indent * . c 

to the shell in an attempt to indent all die C programs in a directory. This is probably a bug, not a feature. 
The -bs option splits an excessivly fine hair. 
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NAME 

login - sign on 

SYNOPSIS 

login [ username ] 

DESCRIPTION 

login signs username on to the system initially; login may also be used at any time to change from one 
userid to another. 

When used with no argument, login requests a user name and password (if appropriate). Echoing is turned 
off (if possible) while typing the password. 

When successful, login updates accounting files, informs you of the existence of any mail, prints the mes- 
sage of the day, and displays the time you last logged in (unless you have a .hushlogin file in your home 
directory — mainly used by nonhuman users, such as uucp). 

login initializes the user and group IDs and the working directory, then starts a command interpreter shell 
(usually either fbin/sh or Ibinlcsh according to specifications found in the file I etc/passwd . (Argument 0 of 
the command interpreter is “-sh”, or more generally, the name of the command interpreter with a leading 
dash (“-”) prepended.) 

login also initializes the environment with information specifying home directory, command interpreter, 
terminal-type (if available) and username. 

If the file ! etc! nolo gin exists, login prints its contents on the user’s terminal and exits. This is used by shut- 
down (&) to stop logins when the system is about to go down. If the file fetc/securetty exists, only those ter- 
minals listed in that file provide login access to the super-user root. For example, if the file contained: 

console 



The super-user could only log in on the console. 

The login command, recognized by sh and csh 9 is executed directly (without forking), and terminates that 
shell. To resume working, you must log in again. 

login times out and exits if its prompt for input is not answered within a reasonable time. 

When the Bourne shell {sh) starts up, it reads a file called , profile from your home directory (that of the 
username you use to log in). When the C-Shell (csh) starts up, it reads a file called xshrc from your home 
directory, and then reads a file called .login. 

The shells read these files only if they are owned by the person logging in. 



FILES 

lusrfadmJlastlog 

lusrfadm/wtmp 

fusrfspoollmailt* 

lusrlttytype 

lusrlucbf quota 

1. hushlogin 

letcfmotd 

letc/nologin 

letcfpasswd 

letc/securetty 

letclutmp 



time of last login 

accounting 

mail 

terminal types 
quota check 
makes login quieter 
message-of-the-day 
stop login, print message 
password file 

terminals allowing the super-user to log in 
accounting 



SEE ALSO 

init(8), getty(8), mail(l), passwd(l), passwd(5), environ(SV), shutdown(8), utmp(5) 



DIAGNOSTICS 

‘ ‘Login incorrect,’ ’ if the name or the password is bad (or mistyped). 

“No Shell”, “cannot open password file”, “no directory”: ask your system administrator for assistance. 
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NAME 

lpr - send job to printer 
SYNOPSIS 

lpr [ -P printer ] [ -#num ] [ -C class ] [ -Jjob ] [ -T title ] [ -i [ num ] ] [ -1234 [font ] 

[—wnum ] [ -B ] [ — r ] [ — m ] [ -h ] [ -s ] [ -filter-option ] [filename . . . ] 

DESCRIPTION 

lpr uses a spooling daemon to print the named files when facilities become available, lpr reads the stndard 
input if no files are specified. 

OPTIONS 

— P printer 

Send output to the named printer . Otherwise send output to the printer named in the PRINTER 
environment variable, or to the default printer, lp. If there is no entry in fetclprintcap for Ip , lpr 
supplies a default set of printer capabilities. 

-#num Produce multiple copies of output, using num as the number of copies for each file named. For 
example, 

tutorial% lpr -#3 new.index.c print.index.c more.c 

produces three copies of the file new index x , followed by three copies of print .index x , etc. On the other 
hand, 

tutorial% cat new.index.c print.index.c more.c | lpr -#3 
generates three copies of the concatenation of the files. 

-C Print class as the job classification on the burst page. For example, 
tutorial% lpr -C Operations new.index.c 

replaces the system name (the name returned by hostname) with ‘Operations’ on the burst page, 
and prints the file newJndexx . 

-J job Print job as the job name on the burst page. Normally, lpr uses the first file’s name. 

-T title Use title instead of the file name for the title used by pr. 

-i[num] Indent output num spaces. If num is not given, eight spaces are used as default 

-1 font 
—Ifont 
-5 font 

-4 font Mount the specified font on font position 1, 2, 3 cm* 4. The daemon will construct a .railmag file in 
the spool directory that indicates the mount by referencing lusr/lib/yfontlfont. 

-w num Use num as the page width for pr. 

-r Remove the file upon completion of spooling. -B Omit page headers. 

-m Send mail upon completion. 

-h Suppress printing the burst page. 

-s Create a symbolic link from the spool area to the data files rather than trying to copy them (so 
large files can be printed). This means the data files should not be modified or removed until they 
have been printed. In the absence of this option, files larger than 1 Megabyte in length are trun- 
cated. Note that the -s option only works on the local host (files sent to remote printer hosts are 
copied anyway), and only with named data files — it doesn’t work if lpr is at the end of a pipeline. 

filter-option 

The following single letter options notify the line printer spooler that the files are not standard text 
files. The spooling daemon will use the appropriate filters to print the data accordingly. 

-p Use pr to format the files (lpr -p is very much like pr | lpr). 

-I Print control characters and suppress page breaks. 

-t The files contain troff (cat phototypesetter) binary data. 
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-n The files contain data from ditroff (device independent troff). 

-d The files contain data from tex (DVI format from Stanford). 

-g The files contain standard plot data as produced by the plot( 3X) routines (see also 
plot( 1G) for the filters used by the printer spooler). 

-v The files contain a faster image, see rasterfile(5). 

-c This option currently is unassigned. 

Hf Interpret the first character of each line as a standard FORTRAN carriage control charac- 
ter. 



If no filter-option is given, ‘%!’ as the first two characters indicates that the file contains 
Postscript commands. 



FILES 

/etc/passwd 
/etc/printcap 
/usr/lib/lpd* 
/usr/spool/* 
/usr/spool/ */cf* 
/usr/spool/ */df* 
/usr/spool/ */tf* 



personal identification 
printer capabilities data base 
line printer daemons 
directories used for spooling 
daemon control files 
data files specified in “cf ’ files 
temporary copies of “cf ’ files 



SEE ALSO 

lpq(l), lprm(l), pr(lV), printcap(5), lpc(8), lpd(8), rasterfile(S), screendump(l) 



DIAGNOSTICS 

lpr: copy file is too large 

A file is determined to be too ‘large’ to print by copying into the spool area. Use the -s option as 
defined above to make a symbolic link to the file instead of copying it. A ‘large’ file is approxi- 
mately 1 Megabyte in this system. 

lpr: printer : unknown printer 

The printer was not found in the printcap database. Usually this is a typing mistake; however, it 
may indicate a missing or incorrect entry in the / etc/printcap file. 

lpr: printer : jobs queued, but cannot start daemon. 

The connection to Ipd on the local machine failed. This usually means the printer server started at 
boot time has died or is hung. Check the local socket Idevlprinter to be sure it still exists (if it 
does not exist, there is no Ipd process running). 

lpr: printer : printer queue is disabled 

This means the queue was turned off with 
tutorial% /usr/etc/lpc disable printer 

to prevent lpr from putting files in the queue. This is normally done by the system manager when a printer 
is going to be down for a long time. The printer can be turned back on by a super-user with Ipc. 

If the -f and -s flags are combined as follows: 
lpr -fs filename 

copies the file to the spooling directory rather than making a symbolic link. 

Placing the -s flag first, or writing each as separate arguments makes a link as expected. 

BUGS 

lpr -p is not equivalent to pr | lpr. lpr -p puts the current date at the top of each page, rather than the date 
last modified, and inserts a header page between each file printed. 

The -p and — # options don’t work well together; the second and subsequent copies do not include the file 
name in each page’s title. 
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Fonts for troff and tex reside on the host with the printer. It is currently not possible to use local font 
libraries. 
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SEE ALSO 

adb(l), dbxtool(l), dbx(l) 

BUGS 

A file name argument can’t start with +. A hexadecimal offset can’t be a block count. Only one file name 
argument can be given. 

It is an historical botch to require specification of object, radix, and sign representation in a single character 
argument 
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NAME 

on - execute a command remotely 
SYNOPSIS 

on [ — i ] [ — n ] [ — d ] host command [ argument ] . . . 

DESCRIPTION 

The on program is used to execute commands on another system, in an environment similar to that invok- 
ing the program. All environment variables are passed, and the current working directory is preserved. To 
preserve the working directory, the working file system must be either already mounted on the host or be 
exported to it. Relative path names will only work if they are within the current file system; absolute path 
names may cause problems. 

Standard input is connected to standard input of the remote command, and standard output and standard 
error from die remote command are sent to the corresponding files for the on command. 



OPTIONS 

-i Interactive mode: use remote echoing and special character processing. This option is 

needed for programs that expect to be talking to a terminal. All terminal modes and win- 
dow size changes are propagated. 

-n No Input: this option causes the remote program to get end-of-file when it reads from 

standard input, instead of passing standard input from the standard input of the on pro- 
gram. For example, -n is necessary when running commands in the background with job 
control. 

-d Debug mode: print out some messages as work is being done. 

SEE ALSO 

rexd(8), exports(5) 



DIAGNOSTICS 

unknown host 
cannot connect to server 
can’t find . 

can’t locate mount point 



Host name not found 
Host down or not running the server 
Problem finding the working directory 
Problem finding current file system 



Other error messages may be passed back from the server. 



BUGS 

The SunView window system can get confused by the environment variables. 
When the working directory is remote mounted over NFS, a A Z hangs the window. 
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NAME 

overview - run a program from SunView that takes over the screen 
SYNOPSIS 

overview [ — w ] [ generic _tool Jiags ] program name [ arguments ] . . . 

DESCRIPTION 

Bitmap graphics based programs that are not SunView based can be run from SunView using overview. 
Overview shows an icon in SunView when overview is brought up iconic (-Wi flag) or when the program 
being run by overview is suspended (for example using ctrl-Z). Opening the overview icon, or starting 
overview non-iconic, starts the program named on the command line. Overview supresses SunView so that 
SunView window applications won’t interfere with the program’s display output or input devices. 

Overview runs programs that fit the following profile: 

own display The program needs to own the bits on the screen. It doesn’t use the sunwin- 

dow or suntool libraries to arbitrate the use of the display and input devices 
between processes. 

keyboard input from stdin The program takes keyboard input from stdin directly. 

mouse input from / dev f mo use The program takes locator input from the mouse directly. 

OPTIONS 

-w This flag is used to specify that the program being run creates its own SunWindows window in 
order to receive the serialized input stream from the keyboard and mouse that is provided by the 
SunWindows kernel driver, -w tells overview to not convert SunWindows input into ascii which 
is then sent to the program being run under overview via a pty. X and NeWS are programs that fall 
in this category (as of Dec 86, which is subject to change in the future). 

SEE ALSO 

Windows and Window-Based Tools : Beginner' s Guide 

BUGS 

Users of overview on a Sun-3/110 frame buffer multiple frames should be aware of the existence of plane 
groups for pre-3.2 applications. You can’t successfully run pre-3.2 applications under overview if overview 
itself is running in the color buffer. If you start overview so that it is not running in the overlay plane, then 
the enable plane isn’t be properly set up for viewing the application. This means that you can’t run over- 
view with the -Wf or -Wb generic tool arguments. Also, you can’t run overview on a desktop created by 
suntools using the -8bit_color_only option. 
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NAME 

pack, peat, unpack - compress and expand files 
SYNOPSIS 

pack [- ] [ -f ] filename . . . 
peat filename . . . 
unpack filename . . . 

DESCRIPTION 

pack attempts to store the specified files in a packed form using Huffman (minimum redundancy) codes on 
a byte-by-byte basis. Wherever possible (and useful), each input file filename is replaced by a packed file 
filenames, with the same access modes, access and modified dates, and owner as those of filename. If pack 
is successful, filename will be removed. 

Packed files can be restored to their original form using unpack or peat. 

The amount of compression obtained depends on the size of the input file and the frequency distribution of 
its characters. 

Because a decoding tree forms the first part of each .z file, it is usually not worthwhile to pack files smaller 
than three blocks unless the distribution of characters is very skewed. This may occur with printer plots or 
pictures. 

Typically, large text-files are reduced to 60-75% of their original size. Load modules, which use a larger 
character set and have a more uniform distribution of characters, show little compression. Their packed 
versions come in at about 90% of the original size. 

No packing will occur if: 

the file appears to be already packed 

the file name has more than 12 characters 

the file has links 

the file is a directory 

the file cannot be opened 

no disk storage blocks will be saved by packing 

a file called name. z already exists 

the .z file cannot be created 

an I/O error occurred during processing 

The last segment of the filename must contain no more than 12 characters to allow space for the appended 
a : extension. Directories cannot be packed. 

peat does for packed files what cat (IV) does for ordinary files, except that peat cannot be used as a filter. 
The specified files are unpacked and written to the standard output To view a packed file named name a. 
use: 



peat filename. z 

or just: 

peat filename 

To make an unpacked copy without destroying the packed version, use 
peat filename > newname 
Failure may occur if: 

the filename (exclusive of the .z) has more than 12 characters; 

the file cannot be opened; 

the file does not appear to be the output of pack. 
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-b Causes the printing of the body of the SCCS file. 

-e This keyletter implies the d, i, u, f, and t keyletters and is provided for convenience. 

-y[S/D] This keyletter will cause the printing of the delta table entries to stop when the delta just printed 
has the specified SID. If no delta in the table has the specified SID, the entire table is printed If no 
SID is specified the first delta in the delta table is printed This keyletter will cause the entire delta 
table entry for each delta to be printed as a single line (the newlines in the normal multi-line for- 
mat of the d keyletter are replaced by blanks) preceded by the name of the SCCS file being pro- 
cessed followed by a followed by a tab. This keyletter is effective only if the d keyletter is also 
specified (or assumed). 

-c[cutoff] 

This keyletter will cause the printing of the delta table entries to stop if the delta about to be 
printed is older than the specified cutoff date-time (see get( 1) for the format of date-time). If no 
date-time is supplied the epoch 0000 GMT Jan. 1, 1970 is used. As with the y keyletter, this 
keyletter will cause the entire delta table entry to be printed as a single line and to be preceded by 
the name of the SCCS file being processed followed by a :, followed by a tab. This keyletter is 
effective only if the d keyletter is also specified (or assumed). 

-r[rev-cutoff] 

This keyletter will cause the printing of the delta table entries to begin when the delta about to be 
printed is older than or equal to the specified cutoff date-time (see get( 1) for the format of date- 
time). If no date-time is supplied the epoch 0000 GMT Jan. 1, 1970 is used (In this case, noth- 
ing will be printed). As with the y keyletter, this keyletter will cause the entire delta table entry to 
be printed as a single line and to be preceded by the name of the SCCS file being processed fol- 
lowed by a :, followed by a tab. This keyletter is effective only if the d keyletter is also specified 
(or assumed). 

If any keyletter but y, c, or r is supplied the name of the file being processed (preceded by one newline and 
followed by two newlines) is printed before its contents. 

If none of the u, f, t, or b keyletters is supplied the d keyletter is assumed. 

Note that the s and i keyletters, and the c and r keyletters are mutually exclusive; therefore, they may not 
be specified together on the same prt command 

The form of the delta table as produced by the y, c, and r keyletters makes it easy to sort multiple delta 
tables by time order. For example, die following will print the delta tables of all SCCS files in directory 
sees in reverse chronological order: 

prt -c sees | grep . | sort -rt tab' +2 -3 

When both the y and c or the y and r keyletters are supplied prt will stop printing when the first of the two 
conditions is met 

SEE ALSO 

sccs(l), admin(l), get(l), delta(l), prs(l), what(l), help(l), sccsfile(5) 

Programming Utilities for the Sun Workstation. 

DIAGNOSTICS 

Use help(l) for explanations. 
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NAME 

ps - process status 



SYNOPSIS 

ps [ acCegklsStuvwx ] [ num] [ kernel name ] [ cdump Jile ] [ swap Jile ] 

DESCRIPTION 

ps displays information about processes. Normally, only those processes that are started by you and are 
attached to a controlling terminal (see termio{ 4V)) are shown. Additional categories of processes can be 
added to the display using various options. In particular, the a option allows you to include processes that 
are not owned by you (that do not have your user ID), and the x option allows you to include processes 
without control terminals. When you specify both a and x, you get processes owned by anyone, with or 
without a control terminal, ps displays the process id, under PID; the control terminal (if any), under TT; 
the cpu time used by the process so far, including both user and system time), under CPU; the state of the 
process, under STAT; and finally, an indication of the COMMAND that is running. 

The state is given by a sequence of four letters, for example, ‘RWNA’. 

First letter indicates the runnability of the process: 

R Runnable processes, 

T Stopped processes, 

P Processes in page wait, 

D Processes in disk (or other short term) waits, 

S Processes sleeping for less than about 20 seconds, 

I Processes which are idle (sleeping longer than about 20 seconds). 

Z A child processes that has terminated and is waiting for its parent process to do a 
wait. 



Second letter indicates whether a process is swapped out; 

blank 

(that is, a space) in this position indicates that the process is loaded (in memory). 

W Process is swapped out 

> Process has specified a soft limit on memory requirements and has exceeded that 
limit; such a process is (necessarily) not swapped. 

Third letter indicates whether a process is running with altered CPU scheduling priority (nice): 

blank 

(that is, a space) in this position indicates that the process is running without special 
treatment 

N The process priority is reduced, 

< The process priority has been raised artificially. 

Fourth letter indicates any special treatment of the process for virtual memory replacement. The 
letters correspond to options to the vadvise (2) system call. Currently the possibilities 
are: 

blank 

(that is, a space) in this position stands for VA NORM. 

A Stands for VA_ANOM. An A typically represents a program which is doing gar- 
bage collection. 

S Stands for VA SEQL. An S is typical of large image processing programs which 
are using virtual memory to sequentially address voluminous data. 

Kerneljiame specifies the location of the system namelist. If the k option is given, c dump Jile tells ps 
where to look for core. Otherwise, the core dump is located in the file Ivmcore and this argument is 
ignored. Swap Jile gives the location of a swap file other than the default, Idev/drum . 

OPTIONS 

a Include information about processes owned by others. 

c Display the command name, as stored internally in the system for purposes of accounting, rather than 



320 



Last change: 13 November 1986 



Sun Release 3.4 




PS(1) 



USER COMMANDS 



PS(1) 



the command arguments, which are kept in the process’ address space. This is more reliable, if less 
informative, since the process is free to destroy the latter information. 

C Display raw CPU time in the %CPU field instead of the decaying average. 

e Display the environment as well as the arguments to the command 

g Display all processes. Without this option, ps only prints ‘interesting’ processes. Processes are 
deemed to be uninteresting if they are process group leaders. This normally eliminates top-level 
command interpreters and processes waiting for users to login on free terminals. 

k Normally, kernel name , defaults to /vmunix, c dump Jile is ignored and swap Jile defaults to 
/dev/drum. With the k option in effect, these arguments default to /vmunix, /vmcore, and Idevl drum, 
respectively. 

1 Display a long listing, with fields PPID, CP, PRI, NI, ADDR, SIZE, RSS and WCHAN as described 
below. 

s Adds the size SSIZ of the kernel stack of each process (for use by system maintainers) to the basic 
output format. 

S Display accumulated CPU time used by this process and all of its reaped children. 

tc Restrict output to processes whose controlling terminal is x (which should be specified as printed by 
ps, for example, t3 for tty3, tco for console, tdO for ttydO, t? for processes with no terminal, etc). 
This option must be the last one given. 

u Display user-oriented output This includes fields USER, %CPU, NICE, SIZE, and RSS as described 
below. 

v Display a version of the output containing virtual memory. This includes fields RE, SL, PAGEIN, 
SIZE, RSS, LIM, TS1Z, TRS, %CPU and %MEM, described below. 

w Use a wide output format (132 columns rather than 80); if repeated, that is, ww, use arbitrarily wide 
output. This information is used to decide how much of long commands to print. 

x Include processes with no controlling terminal. 

/turn A process number may be given, in which case the output is restricted to that process. This option 
must also be last 

DISPLAY FORMATS 

Fields which are not common to all output formats: 

USER name of the owner of the process 

%CPU cpu utilization of the process; this is a decaying average over up to a minute of previous (real) 
time. Since the time base over which this is computed varies (since processes may be very 
young) it is possible for the sum of all %CPU fields to exceed 100%. 

NICE (or NI) process scheduling increment (see setpriority( 2) and nice( 3C). 

SIZE virtual size of the process (in kilobyte units). With the u option, values shown include the size 
of the text segment With the v option, values shown do not include the text segment. 

RSS real memory (resident set) size of the process (in kilobyte units) 

LIM soft limit on memory used, specified via a call to getrlimit(2y, if no limit has been specified 

then shown as xx 

TSIZ size of text (shared program) image 
TRS size of resident (real memory) set of text 

%MEM percentage of real memory used by this process. 

RE residency time of the process (seconds in core) 

SL sleep time of the process (seconds blocked) 

PAGEIN number of disk i/o’s resulting from references by the process to pages not loaded in ewe. 

UID numerical user-id of process owner 

PPID numerical id of parent of process 

CP short-term cpu utilization factor (used in scheduling) 
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PRI process priority (non-positive when in non-interruptible wait) 

ADDR page fram number or swap area position 

WCHAN event on which process is waiting (an address in the system), with the initial part of the address 
trimmed off, for example, 80004000 prints as 4000. 



F 



flags associated with process as in <sys/proc.h > : 



SLOAD 

SSYS 

SLOCK 

SSWAP 

STRC 

SWTED 

SULOCK 

SPAGE 

SKEEP 

SOMASK 

SWEXIT 

SPHYSIO 

SVFORK 

SVFDONE 

SNOVM 

SPAGI 

SSEQL 

SUANOM 

STIMO 

SOUSIG 

SOWEUPC 

SSEL 

S LOG IN 

SPTECHG 



0000001 in core 

0000002 swapper or pager process 
0000004 process being swapped out 
0000008 save area flag 
0000010 process is being traced 
0000020 another tracing flag 
0000040 user settable lock in core 
0000080 process in page wait state 
0000100 another flag to prevent swap out 
0000200 restore old mask after taking signal 
0000400 working on exiting 
0000800 doing physical i/o (bio.c) 

0001000 process resulted from vfoik() 

0002000 another vfork flag 
0004000 no vra, parent in a vfork() 

0008000 init data space on demand, from inode 
0010000 user warned of sequential vm behavior 
0020000 user warned of anomalous vm behavior 
0040000 timing out during sleep 
0100000 using old signal mechanism 
0200000 owe process an addupc() call at next ast 
0400000 selecting; wakeup/waiting danger 
0800000 a login process (legit child of init) 
1000000 pte’s for process have changed 



A process that has exited and has a parent, but has not yet been waited for by the parent is marked 
<defunct>; a process which is blocked trying to exit is marked <exiting>; ps makes an educated guess as to 
the file name and arguments given when the process was created by examining memory or the swap area. 
The method is inherently somewhat unreliable and in any event a process is entitled to destroy this infor- 
mation, so the names cannot be counted on too much. 



FILES 

/vmunix system namelist 
/dev/kmem kernel memory 
/dev/drum swap device 
/vmcore core file 

/dev searched to find swap device and terminal names 



SEE ALSO 

kill(l), w(l), pstat(8), termio(4V) 



BUGS 

Things can change while ps is running; the picture it gives is only a close approximation to the current 
state. 
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NAME 

ranlib - convert archives to random libraries 
SYNOPSIS 

ranlib [ -t ] archive . . . 

DESCRIPTION 

ranlib converts each archive to a form that can be linked more rapidly, ranlib does this by adding a table 

of contents called .SYMDEF to the beginning of the archive, ranlib uses ar(l) to reconstruct the 

archive. Sufficient temporary file space must be available in the file system that contains the current direc- 
tory. 

OPTIONS 

-t option, ranlib only "touches" the archives and does not modify them. This is useful after copying 
an archive or using the -t option of make( 1) in order to avoid having ld( 1) complain about an 
“out of date” symbol table. 

SEE ALSO 

ld(l), ar(l), lorder(l), make(l) 

BUGS 

Because generation of a library by car and randomization of the library by ranlib are separate processes, 
phase errors are possible. The linker, Id, warns when the modification date of a library is more recent than 
the creation date of its dictionary; but this means that you get the warning even if you only copy the 
library. 
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NAME 

rasfilter8tol - convert an 8-bit deep rasterfile to a 1-bit deep rasterfile 
SYNOPSIS 

rasfi!ter8tol [ — d ] [ -rgba threshold ] [ infile [ outfile ]] 

DESCRIPTION 

Rasfilter8tol reads the 8-bit deep rasterfile infile (standard input default) and converts it to the 1-bit deep 
rasterfile outfile (standard output default) by thresholding or ordered dither. The output format is Sun stan- 
dard rasterfile format (see lusr/includelrasterfile.h). This command is useful for viewing 8-bit rasterfiles 
on devices that can only display monochrome images. 

OPTIONS 

-d Use ordered dither to convert the input file instead of thresholding. 

-rgba threshold 

Set the threshold for the red, green, blue, and average pixel color values. Pixels whose color 
values are greater than or equal to all of the thresholds are given a value of 0 (white) in the output 
rasterfile; other pixels are set to 1 (black). The average threshold defaults to 128, the individual 
thresholds to zero. 



EXAMPLE 

The command 

tutorial% screendump -f /dev/cgtwoO | rasfilter8tol | lpr -Pversatec -v 

prints a monochromatic representation of the /dev/cgtwoO frame buffer on the printer named "versatec" 
using the "v" output filter (see /ete/printeap). 

FILES 

/usr/lib/rasfilters/* Filters for non-standard rasterfile formats 

SEE ALSO 

lpr(l), rastrepl(l), screendump(l), screenload(l) 

File HO Facilities for Pixrects in Pixrect Reference Manual 
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NAME 

rastrepl - magnify a raster image by a factor of two 
SYNOPSIS 

rastrepl [ infile [ outfile ]] ]] 

DESCRIPTION 

Rastrepl reads the rasterfile infile (standard input default) and converts it to the rasterfile outfile (standard 
output default) which is twice as large in width and height Pixel replication is used to magnify the image. 
The output file has the same type as the input file. 

EXAMPLES 

tutorial% screendump | rastrepl | Ipr -Pversatec -v 

sends a rasterfile containing the current frame buffer contents to the Versatec plotter, doubling the size of 
the image so that it fills a single page. 

FILES 

/usr/lib/rasfilters/* Filters for non-standard rasterfile formats 

SEE ALSO 

lpr(l), screendump(l), screenload(l) 

File I/O Facilities for Pixrects in Pixrect Reference Manual 
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NAME 

ratfor - rational FORTRAN dialect 
SYNOPSIS 

ratfor [~6c ] [ -C ] [-h ] [ filename ... ] 

DESCRIPTION 

ratfor converts the rational FORTRAN dialect into ordinary FORTRAN 77. It provides control flow con- 
structs essentially identical to those in C. See die FORTRAN 77 Programmer’ s Guide for a description of the 
Ratfor language. 

OPTIONS 

-6c Use the character c as the continuation character in column 6 when translating to FORTRAN. The 
default is to use the & character as a continuation character. 

-C Pass Ratfor comments through to the translated code. 

-h Translate Ratfor string constants to Hollerith constants of the form nnnh string. Otherwise just 
pass the strings through to the translated code. 

SEE ALSO 

f77(l) 

Ratfor in the FORTRAN Programmer’ s Guide 
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NAME 

rep - remote file copy 
SYNOPSIS 

rep filenamel filename2 
rep [— r ] filename . . . directory 
DESCRIPTION 

rep copies files between machines. Each filename or directory argument is either a remote file name of the 
form: 

rhost ipath 

or a local file name (containing no V characters, or a 7’ before any Vs). 

If a filename is not a full path name, it is interpreted relative to your login directory on rhost. A path on a 
remote host may be quoted (using \, ”, or ') so that the metacharacters are interpreted remotely. 

rep does not prompt for passwords; your current local user name must exist on rhost and allow remote 
command execution by rsh(\C). 

rep handles third party copies, where neither source nor target files are on the current machine. Hostnames 
may also take the form rhost jrname to copy files relative to the home directory of the user named rname , 
rather than the current user name on the remote host 

OPTIONS 

-p Preserve modification times and access times. 

-r copy each subtree rooted at filename ; in this case the destination must be a directory. 

SEE ALSO 

ftp(lC), rsh(lC), rlogin(lC) 

BUGS 

rep is meant to copy between different hosts; attempting to rep a file onto itself (as with ”myhost% rep 
tmp/file myhostJtmpIfile ") results in a severely corrupted file. 

rep doesn’t detect all cases where the target of a copy might be a file in cases where only a directory should 
be legal. 

rep can become confused by output generated by commands in a .j profile , . eshre , or .login file on the 
remote host. 

rep doesn’t copy ownership, mode, and timestamps to the new files. 

rep requires that the source host have permission to execute commands on the remote host when doing 
third-party copies. 

If you forget to quote metacharacters intended for the remote host you get an incomprehesible error mes- 
sage. 
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NAME 

rdist - remote file distribution program 
SYNOPSIS 

rdist [ -nqbRhivwy ] [ -f distfile ] [ -d var=value ] [ -m host ] [ name ... ] 
rdist [ -nqbRhivwy ] -c name ... [login@]host[:dest] 

DESCRIPTION 

Rdist is a program to maintain identical copies of files over multiple hosts. It preserves the owner, group, 
mode, and mtime of files if possible and can update programs that are executing. Rdist reads commands 
from distfile to direct the updating of files and/or directories. If distfile is the standard input is used. If 
no -f option is present, the program looks first for ‘distfile’, then ‘Distfile’ to use as the input. If no names 
are specified on the command line, rdist will update all of the files and directories listed in distfile. Other- 
wise, the argument is taken to be the name of a file to be updated or the label of a command to execute. If 
label and file names conflict, it is assumed to be a label. These may be used together to update specific files 
using specific commands. 

The — c option forces rdist to interpret the remaining arguments as a small distfile. The equivalent distfile is 
as follows. 

( name ... ) -> [login@]host 
install [dest] ; 



Other options: 

-d Define var to have value. The -d option is used to define or override variable definitions in the 
distfile. Value can be the empty string, one name, or a list of names surrounded by parentheses 
and separated by tabs and/or spaces. 

-m Limit which machines are to be updated. Multiple -m arguments can be given to limit updates to 
a subset of the hosts listed in the distfile. 

-n Print the commands without executing them. This option is useful for debugging distfile. 

-q Quiet mode. Files that are being modified are normally printed on standard output. The -q option 
suppresses this. 

-R Remove extraneous files. If a directory is being updated, any files that exist on the remote host 
that do not exist in the master directory are removed. This is useful for maintaining truely identi- 
cal copies of directories. 

-h Follow symbolic links. Copy the file that the link points to rather than the link itself. 

-i Ignore unresolved links. Rdist will normally try to maintain the link structure of files being 

transfered and warn the user if all the links cannot be found. 

-v Verify that the files are up to date on all the hosts. Any files that are out of date will be displayed 
but no files will be changed nor any mail sent. 

-w Whole mode. The whole file name is appended to the destination directory name. Normally, only 
the last component of a name is used when renaming files. This will preserve the directory struc- 
ture of the files being copied instead of flattening the directory structure. For example, renaming a 
list of files such as ( dirl/fl dir2/f2 ) to dir3 would create files dir3/dirl/fl and dir3/dir2/f2 instead 
of dir3/fl and dir3/f2. 

-y Younger mode. Files are normally updated if their mtime and size (see stat( 2» disagree. The -y 
option causes rdist not to update files that are younger than the master copy. This can be used to 
prevent newer copies on other hosts from being replaced. A warning message is printed for files 
which are newer than the master copy. 

-b Binary comparison. Perform a binary comparison and update files if they differ rather than 
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comparing dates and sizes. 

Distfile contains a sequence of entries that specify the files to be copied, the destination hosts, and what 
operations to perform to do the updating. Each entry has one of the following formats. 

<variable name> *=’ <name list> 

[ label: ] <source list> *->’ <destination list> <command list> 

[ label: ] <source list> *::’ <time_stamp file> <command list> 

The first format is used for defining variables. The second format is used for distributing files to other 
hosts. The third format is used for making lists of files that have been changed since some given date. The 
source list specifies a list of files and/or directories on the local host which are to be used as the master 
copy for distribution. The destination list is the list of hosts to which these files are to be copied. Each file 
in the source list is added to a list of changes if the file is out of date on the host being updated (second for- 
mat) or the file is newer than the time stamp file (third format). 

Labels are optional. They are used to identify a command for partial updates. 

Newlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with 
‘#’ and end with a newline. 

Variables to be expanded begin with *$’ followed by one character or a name enclosed in curly braces (see 
the examples at the end). 

The source and destination lists have the following format: 

<name> 

or 

*(’ <zero or more names separated by white-space> *)’ 

The shell meta-characters T, *]’, *}’, and *?’ are recognized and expanded (on the local host only) 

in the same way as cs/i(l). They can be escaped with a backslash. The character is also expanded in 
the same way as csh but is expanded separately on the local and destination hosts. When the -w option is 
used with a file name that begins with everything except the home directory is appended to the destina- 
tion name. File names which do not begin with 7’ or use the destination user’s home directory as the 
root directory for the rest of the file name. 

The command list consists of zero or more commands of the following format. 

‘install’ <options> optdestname 
‘notify’ <namelist>‘;’ 

‘except’ <name list>‘;’ 

‘except_pat’ <pattem list>‘;’ 

‘special’ <name list>string ‘ ; ’ 

The install command is used to copy out of date files and/or directories. Each source file is copied to each 
host in the destination list Directories are recursively copied in the same way. Opt dest name is an 
optional parameter to rename files. If no install command appears in the command list or die destination 
name is not specified, the source file name is used. Directories in the path name will be created if they do 
not exist on the remote host. To help prevent disasters, a non-empty directory on a target host will never be 
replaced with a regular file or a symbolic link. However, under the ‘-R’ option a non-empty directory will 
be removed if the corresponding filename is completely absent on the master host The options are ‘-R’, 
‘-h’, ‘-i\ ‘-v’, ‘-w’, ‘-y’, and ‘-b’ and have the same semantics as options on the command line except 
they only apply to the files in the source list The login name used on the destination host is the same as the 
local host unless the destination name is of the format “login@host”. 
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The notify command is used to mail the list of files updated (and any errors that may have occured) to the 
listed names. If no appears in the name, the destination host is appended to the name (e.g., 
namel@host, name2@host, ...). 

The except command is used to update all of the files in the source list except for the files listed in name 
list. This is usually used to copy everything in a directory except certain files. 

The except _pat command is like the except command except that pattern list is a list of regular expressions 
(see ed( 1) for details). If one of the patterns matches some string within a file name, that file will be 
ignored. Note that since V is a quote character, it must be doubled to become part of the regular expres- 
sion. Variables are expanded in pattern list but not shell file pattern matching characters. To include a *$’, 
it must be escaped with ‘V. 

The special command is used to specify sh( 1) commands that are to be executed on the remote host after 
the file in name list is updated or installed. If the name list is omitted then the shell commands will be exe- 
cuted for every file updated or installed. The shell variable ‘FILE’ is set to the current filename before exe- 
cuting the commands in string. String starts and ends with and can cross multiple lines in distfde. Mul- 
tiple commands to the shell should be separated by Commands are executed in the user’s home direc- 
tory on the host being updated. The special command can be used to rebuild private databases, etc. after a 
program has been updated. 

The following is a small example. 

HOSTS = ( matisse root@arpa ) 

FILES = ( /bin /lib /usr/bin /usr/games 

/usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h} 

/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) 

EXLIB = ( Mail.rc aliases aliases.dir aliases .pag crontab dshrc 

sendmaiLcf sendmail.fc sendmail-hf sendmail.st uucp vfont ) 

${FHJES} -> $ {HOSTS} 
install -R ; 

except /usr/lib/${EXLIB} ; 
except /usr/games/lib ; 

special /usr/lib/sendmail "/usr/lib/sendmail -bz" ; 



srcs: 

/usr/src/bin -> arpa 

except_pat ( \\.o\$ /SCCS\$ ) ; 

IMAGEN = (ips dviimp catdvi) 

imagen: 

/usr/local/${IMAGEN} -> arpa 
install /usr/local/lib ; 
notify ralph ; 

${FILES} :: stampxory 

notify root@cory ; 



FILES 

distfile input command file 
/tmp/rdist* temporary file for update lists 
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SEE ALSO 

sh(l), csh(l), stat(2) 

DIAGNOSTICS 

A complaint about mismatch of rdist version numbers may really stem from some problem with starting 
your shell, e.g., you are in too many groups. 

BUGS 

Source files must reside on the local host where rdist is executed. 

There is no easy way to have a special command executed after all files in a directory have been updated. 
Variable expansion only works for name lists; there should be a general macro facility. 

Rdist aborts on files which have a negative mtime (before Jan 1, 1970). 

There should be a ‘force’ option to allow replacement of non-empty directories by regular files or sym- 
links. A means of updating file modes and owners of otherwise identical files is also needed. 
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NAME 

refer - find and insert literature references in documents 
SYNOPSIS 

refer [-ar ] [-b] [ -c string ] [ — « ] [-kx ] [ -Imsi ] [ -p file ] [ -n ] [ skeys ] file . . . 

DESCRIPTION 

Refer is a preprocessor for nrofffl), or trofff 1), that finds and formats references. The input files (standard 
input by default) are copied to the standard output, except for lines between .[ and .] command lines, Such 
lines are assumed to contain keywords as for lookbibil), and are replaced by information from a biblio- 
graphic data base. The user can avoid the search, override fields from it, or add new fields. The reference 
data, from whatever source, is assigned to a set of troff strings. Macro packages such as ms( 7) print the 
finished reference text from these strings. A flag is placed in the text at the point of reference. By default, 
the references are indicated by numbers. 

When refer is used with eqn( 1), neqn( 1), or tbl( 1), refer should be used first in the sequence, to minimize 
the volume of data passed through pipes. 

OPTIONS 

-a r Reverse the first r author names (Jones, J. A. instead of J. A. Jones). If r is omitted, all author 

names are reversed. 

-b Bare mode — do not put any flags in text (neither numbers or labels). 

- cstring 

Capitalize (with Small Caps) the fields whose key-letters are in string. 

-e Accumulate references instead of leaving the references where encountered, until a sequence of 
the form: 

-[ 

$LIST$ 

•] 

is encountered, and then write out all references collected so far. Collapse references to the same 
source. 

-kx Instead of numbering references, use labels as specified in a reference data line beginning with the 
characters %x ; By default, x is L. 

~\m,n Instead of numbering references, use labels from the senior author’s last name and the year of 
publication. Only the first m letters of the last name and the last n digits of the date are used. If 
either of morn is omitted, the entire name or date, respectively, is used. 

-p Take the next argument as a file of references to be searched. The default file is searched last 
-n Do not search the default file. 

-s keys Sort references by fields whose key-letters are in the keys string, and permute reference numbers 
in the text accordingly. Using this option implies the -e option. The key-letters in keys may be 
followed by a number indicating how many such fields are used, with a + sign taken as a very 
large number. The default is AD, which sorts on the senior author and date. To sort on all authors 
and then the date, for instance, use the options -sA+T. 

FILES 

/usr/dict/papers directory of default publication lists and indexes 
/usr/lib/refer directory of programs 

SEE ALSO 

addbib(l), indxbib(l), lookbib(l), roffbib(l), sortbib(l) 
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NAME 

screenblank - turn off video when the mouse and keyboard are idle 
SYNOPSIS 

screenblank [ -m ] [ — k ] [ — d interval ] [ -e interval ] [ — f frame buffer ] 

DESCRIPTION 

screenblank turns off the display when the mouse and keyboard are idle for an extended period (the default 
is 10 minutes). 

OPTIONS 

-m Do not check whether the mouse has been idle. 

-k Do not check whether the keyboard has been idle. 

~d interval 

Disable after interval seconds, interval is a number of the form xxxjcxx where each x is a decimal 
digit The default is 600 seconds (10 minutes). 

— e interval 

Enable within interval seconds, interval is the time between successive polls for keyboard or 
mouse activity. If a poll detects keyboard or mouse activity, the display is resumed, interval is a 
number of seconds, of the form xxxjcxx where each x is a decimal digit The default is 0.25 
seconds. 

-f frame buffer 

frame buffer is the path name of the frame buffer on which video disabling/enabling applies. The 
defaults is /dev/fb. 



SEE ALSO 

lockscieen(l) 

BUGS 

When not running suntools( 1), only the RETURN key resumes video display. 
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NAME 

screendump - dump frame buffer image to file 
SYNOPSIS 

screendump [ -ce ] [ — f framebuffer ] [ -t type ] [file ] 

DESCRIPTION 

Screendump reads die contents of a frame buffer and writes the display image to file (standard output 
default) in Sun standard rasterfile format (see /usr/include/rasterfile.h). 

OPTIONS 

-c Dump the frame buffer contents directly without making a temporary copy in a memory pixrect 
Saves time and memory but lengthens the time the frame buffer must be inactive to guarantee a 
consistent screen dump. 

— f framebuffer 

Dump the specified frame buffer device (default /dev/fb). 

-t type Set the output rasterfile type (default 1, RT STANDARD). See /usr/include/rasterfile.h. 

— e Set the output rasterfile type to 2, RT BY lh EN CODED. For most images this saves a 

significant amount of space compared to the standard format 

EXAMPLES 

tutorial% screendump save.this.image 

writes the current contents of the console frame buffer into the file save.this.image. 

tutorial% screendump -f /dev/cgtwoO savexolor .image 
writes the current contents of die color frame buffer /dev/cgtwoO into the file save.color. image. 

tutorial% screendump | lpr -Pversatec -v 

sends a rasterfile containing the current frame buffer to the lineprinter, selecting the printer named “versa- 
tec” and the “v” output filter (see /etc/printcap). 

FILES 

/usr/lib/rasfilters/* Filters for non-standard rasterfile formats 

SEE ALSO 

lpr(l), rasfilter8tol(l), rastrepl(l), screenload(l) 

File I/O Facilities for Pixrects in Pixrect Reference Manual 

BUGS 

The output file or the screen may be corrupted if the frame buffer contents are modified while the dump is 
in progress. 
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NAME 

screenload - load frame buffer image from file 
SYNOPSIS 

screenload [ -dp ] [ -f framebuffer ] [ -bgw ] [ -h count data ... ] [ -i color ] [file ] 

DESCRIPTION 

Screenload reads the Sun standard rasterfile file (see lusr ! include! rasterfile. h) and displays its contents on a 
frame buffer. Screenload is able to display monochrome images on a color display, but cannot display 
color images on a monochrome display. If the input file contains a color image, a frame buffer has not 
been explicitly specified, and /dev/fb is a monochrome frame buffer, screenload will look for a color frame 
buffer with one of the standard names. 

If the image contained in the input file is larger than the actual resolution of the display, screenload clips 
the right and bottom edges of the input image. If the input image is smaller than the display (for example, 
loading an 1152-by-900 image on a 1600-by-1280 high resolution display), screenload centers the image 
on the actual workstation screen and fills the border area with solid black (by default). Various options 
may be used to change the fill pattern. 

OPTIONS 

-d Print a warning message if the display size does not match the rasterfile image. 

-p Wait for a newline to be typed on the standard input before exiting. 

-f framebuffer 

Display the image on the specified frame buffer device (default /dev/fb). 

-b Fill the border area with a pattern of solid ones (default). On a monochrome display this results in 
a black border; on a color display the color map value selected by the -i option determines the 
border color. 

-g Fill the border area with a pattern of “desktop grey”. On a monochrome display this results in a 
border matching the default background pattern used by SunView; on a color display the color 
map value selected by the -i option determines the foreground border color, though the pattern is 
the same as on a monochrome display. 

-w Fill the border area with a pattern of solid zeros. On a monochrome display this results in a white 
border; on a color display die color map value at index 0 determines the border color. 

-h count data ... 

Fill the border area with the bit pattern described by the following count 16-bit hexadecimal con- 
stants. Note that a “1” bit is black and a “0” bit is white on the monochrome display; on a color 
diplay the color map value selected by the -i option determines the border foreground color. The 
number of hex constants in the pattern is limited to 16. 

-i color Fill the border area with the given color value (default 255). 

EXAMPLES 

tutorial% screenload saved.display .image 

loads the raster image contained in the file saved.display. image on the display type indicated by the 
rasterfile header in that file. 

tutorial% screenload -f/dev/cgtwoO monochrome.image 
reloads the raster image in the file monochrome.image on the color frame buffer device / devlcgtwoO . 

tutorial% screenload -hi ffff small .saved.image 
is equivalent to the -b option (fill border with black), while 

tutorial% screenload — h4 8888 8888 2222 2222 small.saved.image 
is equivalent to the -g option (fill border with desktop grey). 

FILES 

/usr/lib/rasfilters/* Filters for non-standard rasterfile formats 
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SEE ALSO 

rasfilter8tol(l), rastrepl(l), screendump(l), screen! oad(l) 
File HO Facilities for Pixrects in Pixrect Reference Manual 
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NAME 

sh - shell, the standard UNIX command interpreter and command-level language 
SYNOPSIS 

sh [ -acefhiknstuvx ] [ arguments ] 

DESCRIPTION 

sh, the Bourne shell, is the standard UNIX command interpreter. It executes commands read from a termi- 
nal or a file. 

Definitions 

A blank is a TAB or a SPACE character. A name is a sequence of letters, digits, or underscores beginning 
with a letter or underscore. A parameter is a name, a digit, or any of the characters *, @, #, ?, — , $, and ! . 

Invocation 

If the shell is invoked through exec (2) and the first character of argument zero is -, commands are initially 
read from $HOMEI. profile, if such a file exists and is owned by you. Thereafter, commands are read as 
described below, which is also the case when the shell is invoked as Ibin/sh . 

OPTIONS 

The flags below are interpreted by the shell on invocation only; unless the -c or -s flag is specified, the first 
argument is assumed to be the name of a file containing commands, and the remaining arguments are 
passed as positional parameters for use with the commands that file contains. 

~c string If the-c flag is present commands are read from string . 

-s If the -s flag is present or if no arguments remain commands are read from the standard input. 

Any remaining arguments specify the positional parameters. Shell output (except for Special 
Commands) is written to file descriptor 2. 

-i If the -i flag is present or if the shell input and output are attached to a terminal, this shell is 

interactive . In this case TERMINATE is ignored (so that kill 0 does not kill an interactive 
shell) and INTERRUPT is caught and ignored (so that wait is interruptible). In all cases, QUIT 
is ignored by the shell. 

The remaining flags and arguments are described under the set command, under Special Commands , 
below. 

USAGE 

Refer to Doing More With UNIX Beginner s Guide for more information about using the shell as a pro- 
gramming language. 

Commands 

A simple command is a sequence of nonblank words separated by blanks. The first word specifies the 
name of the command to be executed. Except as specified below, the remaining words are passed as argu- 
ments to the invoked command. The command name is passed as argument 0 (see exec (2)). The value of 
a command is its exit status if it terminates normally, or (octal) 200 ^status if it terminates abnormally (see 
sigvec (2) for a list of status values). 

A pipeline is a sequence of one or more commands separated by | (or, for historical compatibility, by "). 
The standard output of each command but the last is connected by a pipe (2) to the standard input of the 
next command. Each command is run as a separate process; the shell normally waits for the last command 
to terminate before prompting for or accepting the next input line. The exit status of a pipeline is the exit 
status of its last command. 

A list is a sequence of one or more simple commands or pipelines, separated by ;, &, &&, or | | , and 
optionally terminated by ; or &. Of these four symbols, ; and & have equal precedence, which is lower 
than that of && and | | . The symbols && and j | also have equal precedence. A semicolon (;) causes 
sequential execution of the preceding pipeline; an ampersand (&) causes asynchronous execution of the 
preceding pipeline (the shell does not wait for that pipeline to finish). The symbols && and | | are used to 
indicate condition execution of the list that follows. With && , list is executed only if the preceding pipe- 
line (or command) returns a zero exit status. With | | , list is executed only if the preceding pipeline (or 
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command) returns a nonzero exit status. An arbitrary number of NEWLINEs may appear in a list , instead of 
semicolons, to delimit commands. 

A command is either a simple command or one of the following constructions. Unless otherwise stated, the 
value returned by a command is that of the last simple command executed in the construction. 

for name [ in word ... ] do list done 

Each time a for command is executed, name is set to the next word taken from the in word list. If 
in word ... is omitted, then the for command executes the do list once for each positional param- 
eter that is set (see Parameter Substitution below). Execution ends when there are no more words 
in the list 

case word in [ patter n[ \ pattern ] . . . ) list ;; ] . . . esac 

A case command executes the list associated with the first pattern that matches word. The form 
of the patterns is the same as that used for filename generation (see Filename Generation) except 
that a slash, a leading dot, or a dot immediately following a slash need not be matched explicitly, 
if list then list [ elif list then list ] . . . [ else list ] fi 

The list following if is executed and, if it returns a zero exit status, the list following the first then 
is executed. Otherwise, the list following elif is executed and, if its value is zero, the list follow- 
ing the next then is executed. Failing that, the else list is executed. If no else list or then list is 
executed, then the if command returns a zero exit status, 
while list do list done 

A while command repeatedly executes the while list and, if the exit status of the last command in 
the list is zero, executes the do list; otherwise the loop terminates. If no commands in the do list 
are executed, then the while command returns a zero exit status; until may be used in place of 
while to negate the loop termination test. 

(list) Execute list in a subshell. 

{list;} list is simply executed. 
name 0 {list;} 

Define a function which is referenced by name. The body of the function is the list of commands 
between { and }. Execution of functions is described below (see Execution). 

The following words are only recognized as the first word of a command and when not quoted: 

if then else elif fi case esac for while until do done { } 

Comments 

A word beginning with # causes that word and all the following characters up to a NEWLINE to be ignored. 
Command Substitution 

The standard output from a command enclosed in a pair of grave accents (w) may be used as part or all of 
a word; trailing NEWLINE s are removed. 

Parameter Substitution 

The character $ is used to introduce substitutable parameters. There are two types of parameters, posi- 
tional and keyword. If parameter is a digit, it is a positional parameter. Positional parameters may be 
assigned values by set. Keyword parameters (also known as variables) may be assigned values by writing: 

name=value [ name -value ] ... 

Pattern-matching is not performed on value. There cannot be a function and a variable with the same 
name. 

%{parameter} 

The value, if any, of the parameter is substituted. The braces are required only when parameter is 
followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If param- 
eter is * or all the positional parameters, starting with $1, are substituted (separated by spaces). 
Parameter $0 is set from argument zero when the shell is invoked. 

If the colon (:) is omitted from the following expressions, the shell only checks whether parameter is set or 
not 

%{parameter:—word} 
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If parameter is set and is nonnull, substitute its value; otherwise substitute word . 

%{parame ter:- word} 

If parameter is not set or is null set it to word; the value of the parameter is substituted. Positional 
parameters may not be assigned to in this way. 

${parame ter:! word} 

If parameter is set and is nonnull, substitute its value; otherwise, print word and exit from the 
shell. If word is omitted, the message “parameter null or not set” is printed. 

${parameter:+word} 

If parameter is set and is nonnull, substitute word ; otherwise substitute nothing. 

In the above, word is not evaluated unless it is to be used as the substituted string, so that, in the following 
example, pwd is executed only if d is not set or is null: 

echo ${d:-vpwdv } 

The following parameters are automatically set by the shell: 

# The number of positional parameters in decimal. 

- Flags supplied to the shell on invocation or by the set command. 

? The decimal value returned by the last synchronously executed command. 

$ The process number of this shell. 

! The process number of the last background command invoked. 

The following parameters are used by the shell: 

HOME The default argument (home directory) for the cd command. 

PATH The search path for commands (see Execution below). 

CDPATH 

The search path for the cd command. 

MAIL If this parameter is set to the name of a mail file and the MAILPATH parameter is not set, 
the shell informs the user of the arrival of mail in the specified file. 

MADLCHECK 

This parameter specifies how often (in seconds) the shell will check for the arrival of 
mail in the files specified by the MAILPATH or MAIL parameters. The default value is 
600 seconds (10 minutes). If set to 0, the shell will check before each prompt. 
MAILPATH 

A colon (:) separated list of filenames. If this parameter is set, the shell informs the user 
of the arrival of mail in any of the specified files. Each filename can be followed by % 
and a message that will be printed when the modification time changes. The default mes- 
sage is you have mail . 

PS1 Primary prompt string, by default “$ ”. 

PS2 Secondary prompt string, by default “> ”. 

IFS Internal field separators, normally SPACE, TAB, and NEWLINE. 

SHELL When the shell is invoked, it scans the environment (see Environment below) for this 
name. If it is found and there is an Y in the filename part of its value, the shell becomes 
a restricted shell. 

The shell gives default values to PATH, PS1, PS2, MAELCHECK and IFS. HOME and MAIL are set by 
login(l). 

Blank Interpretation 

After parameter and command substitution, the results of substitution are scanned for internal field separa- 
tor characters (those found in IFS) and split into distinct arguments where such characters are found. 
Explicit null arguments O'" or ") are retained. Implicit null arguments (those resulting from parameters 
that have no values) are removed. 

Filename Generation 

Following substitution, each command word is scanned for the characters *, ?, and [ . If one of these char- 
acters appears the word is regarded as a pattern . The word is replaced with alphabetically sorted filenames 
that match the pattern. If no filename is found that matches the pattern, the word is left unchanged. The 
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character . at the start of a filename or immediately following a /, as well as the character / itself, must be 
matched explicitly. 

* Matches any string, including the null string. 

? Matches any single character. 

[ . . . ] Matches any one of the enclosed characters. A pair of characters separated by - matches 
any character lexically between the pair, inclusive. If the first character following the 
opening "[ " is a “!” any character not enclosed is matched. 

Quoting 

The following characters have a special meaning to the shell and cause termination of a word unless 
quoted: 

; & ( ) | A < > NEWLINE SPACE TAB 

A character may be quoted (i.e., made to stand for itself) by preceding it with a \. The pair \newline is 
ignored. All characters enclosed between a pair of single quote marks ("), except a single quote, are 
quoted. Inside double quote marks parameter and command substitution occurs and \ quotes the char- 
acters \, ", and $. "$*" is equivalent to "$1 $2 . . .", whereas "$<§>" is equivalent to "$1" "$2" 

Prompting 

When used interactively, the shell prompts with the value of PS1 before reading a command. If at any time 
a NEWLINE is typed and further input is needed to complete a command, the secondary prompt (i.e., the 
value of PS2) is issued. 

Input/Output 

Before a command is executed, its input and output may be redirected using a special notation interpreted 
by the shell. The following may appear anywhere in a simple command or may precede or follow a com- 
mand and are not passed on to the invoked command; substitution occurs before word or digit is used: 

<word Use file word as standard input (file descriptor 0). 

>word Use file word as standard output (file descriptor 1). If the file does not exist it is created; 

otherwise, it is truncated to zero length. 

> >word Use file word as standard output. If the file exists output is appended to it (by first seek- 

ing to the end-of-file); otherwise, the file is created. 

< <[-]word The shell input is read up to a line that is the same as word, or to an end-of-file. The 
resulting document becomes the standard input If any character of word is quoted, no 
interpretation is placed upon the characters of the document; otherwise, parameter and 
command substitution occurs, (unescaped) \newline is ignored, and \ must be used to 
quote the characters \, $, and the first character of word . If - is appended to <<, all 
leading TABs are stripped from word , and from the document. 

<&digit Use the file associated with file descriptor digit as standard input. Similarly for the stan- 

dard output using >8cdigit. 

<&- The standard input is closed. Similarly for the standard output using >&-. 

If any of the above is preceded by a digit, the file descriptor which will be associated with the file is that 
specified by the digit (instead of the default 0 or 1). For example: 

... 2>&1 

associates file descriptor 2 with the file currently associated with file descriptor 1. 

The order in which redirections are specified is significant The shell evaluates redirections left-to-right 
For example: 

... \>xxx 2>&1 

first associates file descriptor 1 with file xxx. It associates file descriptor 2 with the file associated with file 
descriptor 1 (i.e. xxx). If the order of redirections were reversed, file descriptor 2 would be associated with 
the terminal (assuming file descriptor 1 had been) and file descriptor 1 would be associated with file xxx. 
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If a command is followed by & the default standard input for the command is the empty file /dev/null. 
Otherwise, the environment for the execution of a command contains the file descriptors of the invoking 
shell as modified by input/output specifications. 

Redirection of output is not allowed in the restricted shell. 

Environment 

The environment (see environ^ 5V)) is a list of name-value pairs that is passed to an executed program in 
the same way as a normal argument list. The shell interacts with the environment in several ways. On 
invocation, the shell scans the environment and creates a parameter for each name found, giving it the 
corresponding value. If the user modifies the value of any of these parameters or creates new parameters, 
none of these affects the environment unless the export command is used to bind the shell’s parameter to 
the environment (see also set -a). A parameter may be removed from the environment with the unset com- 
mand. The environment seen by any executed command is thus composed of any unmodified name-value 
pairs originally inherited by the shell, minus any pairs removed by unset, plus any modifications or addi- 
tions, all of which must be noted in export commands. 

The environment for any simple command may be augmented by prefixing it with one or more assignments 
to parameters. Thus: 

TERM=450 cmd 



and 



(export TERM; TERM=450; cmd) 
are equivalent (as far as the execution of cmd is concerned). 

If the — k flag is set, all keyword arguments are placed in the environment, even if they occur after the com- 
mand name. The following first prints a=b c and c: 

echo a=b c 
set -k 
echo a=b c 

Signals 

The INTERRUPT and QUIT signals for an invoked command are ignored if the command is followed by &; 
otherwise signals have the values inherited by the shell from its parent, with the exception of signal 1 1 (but 
see also the trap command below). 

Execution 

Each time a command is executed, the above substitutions are carried out If the command name matches 
one of the Special Commands listed below, it is executed in the shell process. If the command name does 
not match a Special Command , but matches the name of a defined function, the function is executed in the 
shell process (note how this differs from the execution of shell procedures). The positional parameters $1, 
$2, — are set to the arguments of the function. If the command name matches neither a Special Com- 
mand nor the name of a defined function, a new process is created and an attempt is made to execute the 
command via exec (2). 

The shell parameter PATH defines the search path for the directory containing the command. Alternative 
directory names are separated by a colon (:). The default path is :/bin:/usr/bin (specifying /bin, and 
/ usr/bin , in addition to the current directory). Directories are searched in order. The the current directory 
is specified by a null path name, which can appear immediately after the equal sign (PATH=:...) or 
between the colon delimiters (...::...) anywhere else in the path list If the command name contains a / 
the search path is not used; such commands will not be executed by a restricted shell. Otherwise, each 
directory in the path is searched for an executable file. If the file has execute permission but is not an 
binary executable (see a.out{ 5) for details) it is assumed to be a file containing shell commands. A sub- 
shell is spawned to read it. A parenthesized command is also executed in a subshell. 
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The location in the search path where a command was found is remembered by the shell (to help avoid 
unnecessary execs later). If the command was found in a relative directory, its location must be re- 
determined whenever the current directory changes. The shell forgets all remembered locations whenever 
the PATH variable is changed or the hash -r command is executed (see below). 

Special Commands 

Input/output redirection is now permitted for these commands. File descriptor 1 is the default output loca- 
tion. 

: No effect; the command does nothing. A zero exit code is returned. 

• file Read and execute commands from file and return. The search path specified by PATH is used to 

find the directory containing file. 
break [ n ] 

Exit from the enclosing for or while loop, if any. If n is specified break n levels, 
continue [ n ] 

Resume the next iteration of the enclosing for or while loop. If n is specified resume at the n-th 
enclosing loop, 
cd [ arg ] 

Change the current directory to arg. The shell parameter HOME is the default arg . The shell 
parameter CDPATH defines the search path for the directory containing arg . Alternative directory 
names are separated by a colon (:). The default path is <null> (specifying the current directory). 
Note that the current directory is specified by a null path name, which can appear immediately 
after the equal sign or between the colon delimiters anywhere else in the path list. If arg begins 
with a / the search path is not used. Otherwise, each directory in the path is searched for arg . 
echo [ arg . . . ] 

Echo arguments. See echo (IV) for usage and description, 
eval [ arg . . . ] 

The arguments are read as input to the shell and the resulting command(s) executed, 
exec [ arg . . . ] 

The command specified by the arguments is executed in place of this shell without creating a new 
process. Input/output arguments may appear and, if no other arguments are given, cause file shell 
input/output to be modified, 
exit [ n ] 

Causes a shell to exit with the exit status specified by w. If n is omitted the exit status is that of the 
last command executed (an end-of-file will also cause the shell to exit.) 
export [ name ... ] 

The given names are marked for automatic export to the environment of subsequently-executed 
commands. If no arguments are given, a list of all names that are exported in this shell is printed. 
Function names may not be exported, 
hash [ -r ] [ name . . . ] 

For each name, the location in the search path of the command specified by name is determined 
and remembered by the shell. The -r option causes the shell to forget all remembered locations. 
If no arguments are given, information about remembered commands is presented. Hits is the 
number of times a command has been invoked by the shell process. Cost is a measure of the work 
required to locate a command in the search path. There are certain situations which require that 
the stored location of a command be recalculated. Commands for which this will be done are 
indicated by an asterisk (*) adjacent to the hits information. Cost will be incremented when the 
recalculation is done, 
login [arg ... ] 

Equivalent to exec login arg See login(l) for usage and description. 

pwd Print the current working directory. See pwd(l) for usage and description, 
read [ name . . . ] 

One line is read from the standard input and the first word is assigned to the first name , the second 
word to the second name, etc., with leftover words assigned to the last name . The return code is 0 
unless an end-of-file is encountered. 
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readonly [ name . . . ] 

The given name s are marked readonly and the values of the these names may not be changed by 
subsequent assignment If no arguments are given, a list of all readonly names is printed, 
return [ n ] 

Causes a function to exit with the return value specified by n. If n is omitted, the return status is 
that of the last command executed, 
set [ -aefhkntuvx- [ arg . . . ] ] 

—a Mark variables which are modified or created for export 
-e Exit immediately if a command exits with a nonzero exit status. 

— f Disable filename generation 

— h Locate and remember function commands as functions are defined (function commands 

axe normally located when the function is executed). 

-k All keyword arguments are placed in the environment for a command, not just those that 
precede the command name. 

-n Read commands but do not execute them. 

-t Exit after reading and executing one command. 

-u Treat unset variables as an error when substituting. 

-v Print shell input lines as they are read. 

-x Print commands and their arguments as they are executed. 

- Do not change any of the flags; useful in setting $1 to -. 

Using + rather than - causes these flags to be turned off. These flags can also be used upon invo- 
cation of the shell. The current set of flags may be found in The remaining arguments are 
positional parameters and are assigned, in order, to $1, $2, and so on. If no arguments are given, 
the values of all names are printed, 
shift [ n ] 

The positional parameters are shifted to the left, from position n+1 to position 1, and so on. Previ- 
ous values between $1 and $/t are discarded. If n is not given, it is assumed to be 1. 
test Evaluate conditional expressions. See test (IV) for usage and description, 
times Print the accumulated user and system times for processes run from the shell, 
trap [ arg][n ] ... 

The command arg is to be read and executed when the shell receives signal(s) n. (Note that arg is 
scanned once when the trap is set and once when the trap is taken.) Trap commands are executed 
in order of signal number. Any attempt to set a trap on a signal that was ignored on entry to the 
current shell is ineffective. An attempt to trap on signal 1 1 (memory fault) produces an error. If 
arg is absent all trap(s) n are reset to their original values. If arg is the null string this signal is 
ignored by the shell and by the commands it invokes. If n is 0 the command arg is executed on 
exit from the shell. The trap command with no arguments prints a list of commands associated 
with each signal number, 
type [ name ...] 

For each name, indicate how it would be interpreted if used as a command name, 
umask [ ooo ] 

The user file-creation mode mask is set to ooo. The three octal digits refer to read/write/execute 
permissions for owner, group, and others, respectively. The value of each specified digit is sub- 
tracted from the corresponding ‘digit’ specified by the system for the creation of a file. For exam- 
ple, umask 022 removes group and others write permission (files normally created with mode 777 
become mode 755; files created with mode 666 become mode 644). The current value of the 
mask is printed if ooo is omitted, 
unset [ name ... ] 

For each name, remove the corresponding variable or function. The variables PATH, PS1, PS2, 
MAILCHECK and IFS cannot be unset 
wait [ n ] 

Wait for the specified process and report its termination status. If n is not given all currently 
active child processes are waited for and the return code is zero. 
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EXIT STATUS 

Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. If the 
shell is being used noninteractively execution of the shell file is abandoned. Otherwise, the shell returns 
the exit status of the last command executed (see also the exit command above). 

FILES 

$HOME/ profile 

/tmplsh* 

/dev/ null 
SEE ALSO 

csh(l), cd(l), echo(lV), login(l), pwd(l), test(lV), dup(2), exec(2), fork(2), pipe(2), signal(2), umask(2), 
wait(2), a.out(5), profile(5), environ(5). 

CAVEATS 

If a command is executed, and a command with the same name is installed in a directory in the search path 
before the directory where the original command was found, the shell will continue to exec the original 
command. Use the hash command to correct this situation. 

If you move the current directory or one above it, pwd may not give the correct response. Use the cd com- 
mand with a full path name to correct this situation. 
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NAME 

suntools, othertools, selectionsvc - the SunView window environment 
SYNOPSIS 

suntools [ -n | -s startup-file ] [ -S ] [ -d display-device ] [ -m mouse-device ] [ -k keyboard-device ] 

[— p] [-b red green blue ] [— f red green blue ] [ -i ] [ — B | — F | — P ] 

[ -pattern on | off | gray | iconedit-file-name ] [ -background raster-file-name ] [ 
-8bit_color_only ] [ -toggle enable ] [ -overlay_onIy ] 

GETTING STARTED 

suntools starts up the SunView environment and (unless you have specified otherwise) a default arrange- 
ment of a few useful “tools,” or window-based utilities. 

See Start-up Processing below to learn how to specify your own initial arrangement of tools. Some of the 
behavior of suntools is controlled by settings in your defaults database; see SunView Defaults below. 

OPTIONS 

-n Bypass startup processing by ignoring both the I usrf lib/ suntools and 7 .suntools files. See Startup 
Processing for details. 

— s startup-file 

Read startup commands from startup file (instead of /usrllib/ suntools or 7 suntools). 

-S Set "click- to- type" mode, allowing you to select a window by clicking in it. Having done so, input 

is directed to that window regardless of the position of the mouse-cursor, until you click to select 
some other window. 

— d display-device 

Use display device as the output device on which to run, rather than the default frame buffer dev- 
ice, / dev/fb . 

-m mouse-device 

Use mouse device as the system pointing device (locator), rather than the default mouse device, 
Idevlmouse. 

-k keyboard-device 

Accept keyboard input from keyboard device y rather than the default keyboard device, / dev/kbd . 

-p Prints to standard out the name of the window device used for the suntools Root Window. 

-b red green blue 

Specifies the values of the red, green and blue components of the background color. If this option 
is not specified, each component of the background color is 255 (white). Prism users that use this 
option should use the -8bit_coIor_only option too. 

-f red green blue 

Specifies the values of the red, green and blue components of the foreground color. If this option 
is not specified, each component of the foreground color is 0 (black). Prism users that use this 
option should use the -8bit_color_only option too. 

-i Invert the background and foreground colors used on the screen. On a monochrome monitor, this 
option provides a video reversed image. On a color monitor, colors that are not used as the back- 
ground and foreground are not affected. 

-B Use the background color for the Root Window color. 

-F Use the foreground color for the Root Window color. 

-P Use a stipple pattern for the Root Window color. This option is assumed unless -F or -B is 
specified. 

-pattern [on | off | gray | iconedit-file-name ] 

Use the indicated “pattern” to cover the Root Window, on means to use the default desktop gray 
pattern, off means to not use the default desktop gray pattern, gray means to use a 50% gray 
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color on color monitors, iconedit-file-name is the name of a file produced with iconedit(l) which 
contains an image that is replicated all over the Root Window. 

-background raster-file-name 

Use the indicated raster file as the image in your Root Window. The raster file can be created with 
screendump( 1). Screen dumps produced on color monitors currently do not woik as input to this 
option. Small images are centered on the screen. 

-8blt_color_only 

For multiple plane group frame buffers, only let windows be created in the 8 bit color plane group. 
This frees up the black and white overlay plane to have a separate desktop running on it. This 
option is usually used with the -toggle_enable option. See the section below entitled Multiple 
Deshops on the Same Screen. 

-toggle_enable 

For multiple plane group frame buffers, when sliding the cursor between different desktops run- 
ning within different plane groups on the same screen, change the enable plane to allow viewing 
of the destination desktop. See the section below entitled Multiple Desktops on the Same Screen. 

-overlay_only 

For multiple plane group frame buffers, only let windows be created in the black and white over- 
lay plane group. This frees up the 8 bit color plane group to have a separate desktop running in it. 
This option is usually used with the -toggle_enable option. See the section below entitled Multi- 
ple Deshops on the Same Screen. 

DESCRIPTION 

Windows 

The SunView environment always has one window open, called the Root Window, which covers the whole 
screen. A solid color is its only content Each tool is given its own window which lies on top of some of 
the Root Window (and possibly on top of other tools). A window obscures any part of another window 
which lies below it 

Input to Windows 

Mouse input is always directed to the window the mouse cursor is in. You can have keyboard input follow 
mouse input or you can use the “Click-to-Type” approach. With Click-to-Type, keyboard input contin- 
ues to be directed to a window, no matter where the mouse is pointing, until you click the left or middle 
mouse button in another window. Click-to-Type is an option in your defaults database; see SunView 
Defaults below. If you are not using Click-to-Type, and your mouse cursor is in the Root Window, key- 
board input is discarded. 

Your input actions (mouse motions, button pushes, and keystrokes) are synchronized. This means that you 
can “type-ahead” and “mouse-ahead,” even across windows. 

The Mouse Buttons 

Left button (the select button) Click once to select or choose objects. 

Middle button (the adjust button) Click once to shorten or lengthen your selection. 

Right button (the menu button) Depress and hold down to invoke menus. 

Menus 

suntools provides pop-up menus. In the current release, there are two styles of pop-up menus: the original 
menu style, called stacking menus, and a new style, called walking menus (also known as “pull-right 
menus”). A menu is invoked by pressing and holding the menu button. The menu remains on the screen 
as long as you hold the menu button down. To select a menu item, point at it (it will be highlighted), then 
release the menu button. 

With stacking menus, more than one menu can appear simultaneously. The menus are shown in a stack, 
with the label of each menu visible, and with the current menu on top so that its items are visible. To bring 

a menu to the top (and make its items available), select its label as you would a menu item. Then push the 

menu button again. The menu stack is repainted with the selected menu on top. 
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With walking menus, any menu item can have an arrow ( => ) on the right Pointing to this arrow invokes 
a sub-menu, with additional menu items that can be selected. Selecting an item that has an arrow (a 
“pull-right item”) invokes the first item on the sub-menu. 

Walking menus are an option in your defaults database; see SunView Defaults below. 

The Root Window Menu 

You can use the default Root Window Menu to start ten common tools and perform three functions. To 
invoke it, hold down the menu button when the mouse cursor is anywhere in the Root Window. 

The items in the default Root Window Menu are: 

ShellTool Creates a new shelltool( 1), running a new copy of the shell. 

CommandTool Creates a new cmdtool ( 1 ), a scrollable cousin of the shelltool . 

MailTool Creates a new mailtool(l). 

TextEditor Creates a new textedit(\). 

DefauItsEditor Creates a new defaultsedit(\), for browsing or changing your defaults database. 
IconEditor Creates a new iconedit( 1 ). 

DbxTool Creates a new dbxtool( 1), a window-based debugger. 

PerlMeter Creates a new perfmeter(\), to monitor system performance. 

GraphicsTool Creates a new gfictool ( 1 ), for running graphics programs. 

Console Creates a new Console window, a cmdtool with a -C flag, which acts as the system con- 

sole. In particular, most error messages will be directed to the console. You should 
always have a console window on your screen. 

Lock Screen Completely covers the screen with a graphics display, and “locks” the workstation until 
you type your password. When you “unlock” the workstation, the screen is restored as 
it was when you locked it See lockscreen( 1) for details. 

Redisplay All Redraws all the contents of the screen. Use this to repair damage done by processes that 
wrote to the screen without consulting the SunView system. 

Exit Suntools Exits the suntools program. Closes all tool windows and kills their associated processes 
(depending on the processes, this can be fairly slow). You return to the shell which 
invoked suntools. 

This command requires confirmation: When it prompts you, press the left mouse button 
to complete the Exit Suntools command; press the right button to cancel. 

You can specify your own Root Window Menu; see SunView Defaults below. 

The Frame Menu 

A small set of universal functions are available through the Frame Menu. There are also accelerators for 
some of these functions; see below. 

You can invoke the Frame Menu when the cursor is over any part of the tool which does not provide an 
application-specific menu, such as the tool namestripe (black stripe holding the tool’s name), the border 
stripes of the window, and the whole of the tool’s icon. 

The items in the Frame Menu are: 

Close (Open) Only one of Close or Open appears in the menu, depending on the current state of the 
window. Close shrinks the tool to a small image (an icon). Open reopens an icon and 
places the tool in the spot it occupied when it was open. Icons are placed on the screen 
according to the icon policy in your defaults database; see SunView Defaults below. 
You can move a closed window just like an open window. When the window is closed, 
the tool’s process(es) continue to run. 

Move Moves the tool window to another spot on the screen. When invoked. Move instructs 
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you with an instruction box that appears in the middle of the screen. 

If you are using walking menus, Move has a sub-menu with two items: Constrained 
and Unconstrained. Constrained moves are either vertical or horizontal, but not both. 
Selecting Move invokes a Constrained move. 

Resize Shrinks or stretches the size of a window on the screen. Resize, like Move, instructs 

you with an instruction box that appears in the middle of the screen. 

If you are using walking menus, Resize has a sub-menu with four items: Constrained, 
Unconstrained, Zoom (or UnZoom, depending on the current state of the window) and 
FullScreen. Constrained resizes are either vertical or horizontal, but not both. Zoom 
makes a window the full height of the screen; UnZoom undoes this. FullScreen makes 
a window the full height and width of the screen; UnZoom undoes this. Selecting 
Resize invokes a Constrained resize. 

Brings the window to ‘the top of the pile’. The whole window becomes visible, and 
occludes any window it happens to overlap on the screen. 

Puts the window on the ‘bottom of the pile’. The window is occluded by any window 
which overlaps it. 

Redraws the contents of the window. 

Notifies the tool to terminate gracefully. This command requires the same type of 
confirmation as the Exit Suntools command in the Root Window Menu. 

Frame Menu Accelerators 

Accelerators are provided for some of the Frame Menu functions. You can invoke these functions quickly 
with a simple button push in the tool window’s name stripe or outer boundary, without displaying a menu. 
See Windows and Window-Based Tools: Beginner's Guide for more details. 

The accelerators for the various functions are: 

Open Click the select mouse button when the cursor is over the icon. 

Move Depress the adjust mouse button while the cursor is in the tool’s name stripe or outer 

boundary. A bounding box is displayed which tracks the mouse as long as you hold 
the adjust button down. 

If the cursor is near a comer when you press the mouse button, the move is Uncon- 
strained. If it is in the middle third of a side, the move is Constrained. 

Resize While holding down the CTRL key, depress the adjust mouse button while the cursor 

is in the tool’s name stripe or outer boundary. A bounding box is displayed, one side 
or comer of which tracks the mouse as long as you hold the adjust button down. 

If the cursor is near a comer when you press the mouse button, the resize is Uncon- 
strained. If it is in the middle third of a side, the resize is Constrained. 

Zoom (UnZoom) While holding down the CTRL key, click the select mouse button while the cursor is 
in the tool’s name stripe or outer boundary. 

Expose Click the select mouse button while the cursor is on the tool’s name stripe or outer 

boundary. 

Hide While holding down the shift key, click the select mouse button while the cursor is 

on the tool’s name stripe or outer boundary. 

In addition, you can use two function keys as even faster accelerators. To expose a window that is partially 
hidden, hit the Expose key (normally L5) while the cursor is anywhere in the tool window, not just on the 
tool’s name stripe or outer boundary. Or, if the window is completely exposed, use the Expose key to hide 
it Similarly, to close an open window, hit the Open key (normally L7) while the cursor is anywhere in the 
tool window, not just on the tool’s name stripe or outer boundary. Or, if the window is iconic, use the 
Open key to open it You can change which keys mean Expose and Open by using setkeys( 1). 



Expose 

Hide 

Redisplay 

Quit 
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In many multi-subwindow tools, you can adjust the boundary between two subwindows up or down 
without changing the overall size of the tool. While holding down the CTRL key, depress the adjust mouse 
button over the boundary. A bounding box is displayed for the subwindow selected. Adjust the size of that 
subwindow, exactly as with the Resize operation. 

Startup Processing: The .suntools File 

Unless you override it, suntools will start up with a predefined arrangement of windows. The default 
arrangement is specified by the file /usrllib/suntools. If there is a file called suntools in your home direc- 
tory, that will be used instead. The -s flag on the command line indicates that the initial window arrange- 
ment should be read from a file with a different name. The -n switch suppresses this start-up processing 
altogether. 

To create your own suntools, arrange the screen the way you like, then save the arrangement by running 
toolplaces and redirecting its standard output to .suntools . See toolplaces( 1) for a description of the format 
of this file, or take a look at lusrllibl suntools . 

SunView Defaults 

SunView allows you to customize the behavior of tools and packages by setting options in a defaults data- 
base (one for each user). Use defaultsedit( 1) to browse and edit your defaults database. Select the “Sun- 
View” category to see the following items: 

Walking menus If enabled, the Root Window Menu, the Frame Manager Menu, and many tools will use 
walking menus. Tools that have not been converted will still use stacking menus. If dis- 
abled, all tools will use stacking menus. Default value is “Disabled”. 

Click to Type If enabled, keyboard input will stay in a window until you click the left or middle mouse 
button in another window. If disabled, keyboard input will follow the mouse. Default 
value is “Disabled”. 

Font You can change the SunView default font by giving the full pathname of the font you 

want to use. Some alternate fonts are in the directory lusrlliblfontsffixedwidthfonts . The 
previous (2.0 release) default font is lusrlliblfontslfixedwidthfontslscreen.r. 1 3 . Default 
value is null, which gives you the same effect as if you had specified 
lusrllibffontslfixedwidtffontslscreen.r.ll . 

Rootmenufilename 

You can change the Root Window Menu by giving the full pathname of a file that 
specifies your own menu. See Customizing the Root Window Menu below for details. 
Default value is null, which gives you the menu found in /usr/lib/rootmenu. 

Icon gravity Determines which edge of the screen (“North”, “South”, “East”, or “West”) icons 
will place themselves against Default value is “North”. 

Icon close level Determines whether icons will close ahead of or behind other windows and icons. 
Default value is “Ahead_of_all”. 

J umpcursoronresize 

If enabled, during a resize the cursor will jump to the edge of the window. If disabled, 
the window edge will move to the current location of the cursor. Default value is “Dis- 
abled”. 

Audible J)ell If enabled, the “bell” command will result in a beep. Default value is “Enabled”. 

Visible bell If enabled, the “bell” command will cause the screen to flash. Default value is 
“Enabled”. 

EmboldenLabels 

If enabled, all tool labels are boldface. Default value is “Disabled”. 

Root Pattem Used to specify the “pattern” that covers the Root Window, “on” means to use the 
default desktop gray pattern, “off” means to not use the default desktop gray pattern, 
“gray” means to use a 50% gray color on color monitors. Anything else is the name of 
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a file produced with iconedit{\) which contains an image that is replicated all over the 
Root Window. Default value is “on”. 

After you have set the options you want, click on the Save button in defaultsedit; then exit suntools and res- 
tart it 

Customizing the Root Window Menu 

The file called lusrlliblrootmenu contains the specification of the default Root Window Menu. You can 
change the Root Window Menu by creating your own file and giving its name in the Rootmenu_filename 
item in the SunView Defaults (see above). 

Lines in the file have the following format: The left side is a menu item to be displayed; the right side is a 
command to be executed when that menu item is invoked. You can also include comment lines (beginning 
with a ‘#’) and blank lines. 

If you are using stacking menus (“Walking_menus Disabled” in SunView defaults), the menu item must 
be a string (strings with embedded blanks must be delimited by double quotes). If you are using walking 
menus (‘ ‘ Walking menus Enabled”), the menu item can be a string or the full pathname of an icon file, 
delimited by angle brackets. With care, strings and icons can be mixed in one menu. 

There are four reserved-word commands that can appear on the right side. 

EXIT Exit the suntools program, after user confirmation. 

REFRESH Redraw the entire screen. 

MENU If you are using stacking menus, a menu is added to the pile with the Root Window 

Menu. The menu contents are taken from the filename that follows the MENU com- 
mand. You must give the full pathname of the file. 

If you are using walking menus, this menu item is a pull-right item with a submenu. If a 
filename follows the MENU command, the submenu contents are taken from the 
filename. Otherwise, all the lines between this MENU command and a matching END 
command are added to die submenu. 

END Marks the end of a nested submenu. The left side of this line should match the left side 

of a line with a MENU command. Not valid if you are using stacking menus. 

If the command is not one of these four reserved-word commands, it is treated as a command line and exe- 
cuted. No shell interpretation is done, although you can run a shell as a command. 

Here is a menu file that demonstrates some of these features: 



Quit 


EXIT 


Clock 


clock -r-f 


"Mail reader" 


mail tool 


"More tools" 


MENU /usr/foo/me/moretools.menu 


"Click to type” 


swin-c 


"Follow mouse" 


swin -m 


"Print selection" 


sh-c get selection | lpr 


# Only if you are using walking menus: 


"Nested menu” 


MENU 


Cmdtool 


cmdtool 


Shell tool 


shelltool 


"Nested menu” 


END 


"Icon menu" 


MENU 
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</usr/include/images/textedit.icon> textedit 

</usr/include/images/iconedit.icon> iconedit 

"Icon menu" END 

Multiple /Color Displays 

The suntools program runs on either a monochrome or color screen. Each screen on a machine may have 
its own invocation of suntools running on it The keyboard and mouse input devices are shared among 
multiple screens. The mouse cursor slides from one screen to another when you move the cursor off the 
edge of a screen. 

A common multiple display configuration is one monochrome and one color screen. You could set up an 
instance of suntools on each screen in the following way: 

1. Invoke suntools on the monochrome display by running “suntools”. This starts suntools on the 
default frame buffer named Idevlfb. 

2. In a shelltool, run “suntools -d /dev/cgoneO -n This starts suntools on a color screen named 
/ dev/cgoneO. 

3. In a shelltool on the monochrome screen, run “adjacentscreens /dev/fb -r /dev/cgoneO’ ’ . This sets 
up cursor tracking so that the cursor slides from the monochrome screen to the color screen when 
you move the cursor off the right hand side of the monochrome screen, and back when you move 
the cursor off the left hand side of the color screen. 

Multiple Desktops on the Same Screen 

Given appropriate hardware, the suntools program can be made to run separate desktops on the same 
screen. This facility is an extension of the features described in the previous section entitled 
Multiple / Color Displays. The Prism is an example of a machine with multiple plane groups that can take 
advantage of this facility. Each plane group on a machine may have its own invocation of suntools running 
on it Such an invocation is called a desktop. The keyboard and mouse input devices are shared among 
multiple desktops. The mouse cursor slides from one desktop to another when you move the cursor off the 
edge of the screen. 

A common multiple desktop configuration for the Prism is one monochrome and one color desktop. You 
could set up an instance of suntools on each plane group in the following way: 

1. Invoke suntools in the color plane group by running “suntools -8bit_color_only -toggle_enable”. 
This starts suntools on the default frame buffer named Idevlfb but limits access to the color plane 
group. 

2. In a shelltool, run “suntools -d /dev/bwtwoO -toggle_enable -n This starts suntools in the 
overlay plane that is accessed by /dev/bwtwoO. 

3. In a shelltool run “adjacentscreens -c /dev/fb -1 /dev/bwtwoO”. This sets up cursor tracking so 
that the cursor slides from the monochrome desktop to the color desktop when you move the cur- 
sor off the right hand side of the monochrome desktop, and back when you move the cursor off 
the left hand side of the color desktop. 

Old pre-3.2 applications run on the 8bit_color_only desktop will not appear because they will be writing to 
the overlay plane. I.e., don’t ran old pre-3.2 applications on an 8bit_color_only desktop. 

There is an application called the switcher that is used as an alternative to adjacentscreens for getting 
between desktops on the Prism. Clicking the switcher icon gets you to another desktop using some amus- 
ing video wipe type animation. The switcher can also be used to simply set the enable plane to 0 or 1 if the 
enable plane get out of wack. See the man page switcher\(l) for details. 

Generic Tool Arguments 

Most window-based applications now take the following arguments in their command lines: 

FLAG (LONG FLAG) ARGS NOTES 

-Ww (-width) columns 
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-Wh 


(-height) 


lines 




-Ws 


(-size) 


xy 


x and y are in pixels 


-Wp 


(-position) 


xy 


x and y are in pixels 


-WP 


(-icon_position) 


xy 


x and y are in pixels 


-WI 


(-label) 


"string" 




-Wi 


(-iconic) 




makes the tool start iconic (closed) 


-Wt 


(-font) 


filename 




-Wn 


(-nonamestripe) 






-Wf 


(-foregroundcolor) 


red green blue 


0-255 (no color-full color) 


-Wb 


(-backgroundcolor) 


red green blue 


0-255 (no color-full color) 


-Wg 


(-set_default_color) 




(apply color to subwindows too) 


-WI 


(-iconjumage) 


filename 


(for tools with non-default icons) 


-WL 


(-iconlabel) 


"string" 


(for tools with non-default icons) 


-WT 


(-icon_font) 


filename 


(for tools with non-default icons) 


-WH 


(-help) 




print this table 



Each flag option may be specified in either its short form or its long form; the two are completely 
synonymous. 

Getting Out 

To exit any tool, invoke the Quit command in the Frame Menu as described above. To exit the entire win- 
dow system, invoke Exit Suntools in the Root Window Menu as described above. Make sure that all win- 
dows are in a safe condition (for example, editors have written out all changes) first 

You can exit suntools via the keyboard by typing T) followed by A Q. There is no confirmation. This facil- 
ity provides an escape if you inadvertently start suntools without a mouse attached to the system. 

SEE ALSO 

Windows and Window-Based Tools: Beginner's Guide 

Some of the applications that run in the SunView environment 

clock( 1), cmdtool( 1), dbxtool( 1), defaultsedit ( 1 ), fontedit ( 1 ), gfxtool( 1), iconedit( 1), lock - 
screen^ 1), mail tool (l), overview (1), perfmeter(l), perjmon(l), shelltool{\\ tektool( 1), tex- 
tedit( 1), traffic (l) 

Some of the utility programs that run in or with the SunView environment: 

adjacentscreens{ 1), clear Junctions^ 1), get_selection( 1), rastps(l), setkeys(l), 
stty Jrom_defaults ( 1 ), swin{ 1), switcher {\), toolplaces{\) 

ENVIRONMENT 

DEFAULTS JFTLE 

The value of this environment variable indicates the file from which SunView defaults 
are read. When it is undefined, defaults are read from the .defaults file in your home 
directory. 

FILES 

7.suntools 

/usr/bin/suntools 

/usr/bin/othertools 

/usr/bin/get_selection 

/usr/bin/selection_svc 

/usr/lib/suntools 

/usr/lib/rootmenu 

/usr/lib/fonts/fixedwidthfonts/* 

/dev/wiru 

/dev/ptypx 

/dev/ttypx 
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/dev/fb 

/dev/kbd 

/dev/mouse 

/etc/utmp 

BUGS 

Messages from the kernel ignore window boundaries unless console messages have been redirected, thus 
trashing the display. Recover from this by invoking the Redisplay All item on the Root Window Menu. 
Then invoke the Console item to start a console. 

To improve interactive performance, the kernel should be reconfigured in order to make more memory 
available for applications. See the System Manager's Guide . 

With an optical mouse, sometimes the arrow-shaped cursor will not move at start-up; moving the mouse in 
large circles on its special pad for a few seconds will bring the cursor to life. 

suntools needs the file fetdutmp to have read and write permission for all users. It should have been 
installed with these permissions, but if not, you need to use chmod to change the permissions. 

On a color display, all of the colors may “go strange” when the cursor is in certain windows. This is 
caused by SunView accommodating a particular window’s request for a large number of colors. 

When running multiple desktops, be careful to not have more than one shelltool or cmdtool acting as the 
console at once. Kill one console before starting another. 
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SWIN(l) 



USER COMMANDS 



SWIN(l) 



NAME 

swin - set/get SunView user input options 
SYNOPSIS 

swin [ — c ] [ — g ] [ — h ] [ — m ] [ -r event value shift state ] [ -s event value shift state ] [ -t seconds ] 
DESCRIPTION 

The swin (set window; analogous to stty(l)) command lets you change some of the input behavior of your 
SunView environment. By default, your keyboard input follows your mouse cursor. This means that in 
order to type to a window you position the mouse cursor over the window. This is called keyboard- 
follows-mouse mode. 

You can specify that the keyboard input continues to go to the same window, regardless of the mouse cur- 
sor position, until you take some specific action, like clicking the mouse. When this is done, you can roam 
around the screen with the mouse cursor and not change the window to which keyboard input is directed. 
Running SunView like this is said to be operating in click-to-type mode. 

When running in click-to-type mode, one user action sets the type-in point in the window that you want to 
receive keyboard input The default user action to do this is the pressing of the left mouse button while 
positioning the mouse cursor over the new type-in point This user action can be changed. 

Another user action restores the previous type-in point in the window that you want to receive keyboard 
input The default user action to do this is the pressing of the middle mouse button while positioning the 
mouse cursor over the window. This user action can be changed. 

OPTIONS 

— c Turn on click-to-type mode using the default user actions: the left mouse button sets the type-in 

point and the middle button restores the type-in point You can use the defaultseditfl ) program to 
set click-to-type on permanently; see the SunView/Click_to_Type option. 

-m Run in keyboard-follows-mouse mode. 

-s event value shift_state 

Set the user action that sets the type-in point and sets the keyboard input window. The event 
identifies the particular user action and is one of: 

LOCWINENTER 

the mouse cursor entering a window 

MS_LEFT 

the left mouse button 
MSMIDDLE 

the middle mouse button 
MS_RIGHT 

the right mouse button 

decimal jiumber 

place the decimal number of a firm event here; see list of events in 
/usr/include/sundev/vuid event.h (avoid function keys, normally unused control-ascii 
characters are OK, normally unused shift keys are OK). 

value identifies the transition of the event and is one of: 

enter the mouse cursor entering a window (use with LOC WINENTER) 

down the button associated with event went down 

UP the button associated with event went up (avoid this) 

The shift _state identifies the state of the shift keys at the time of the event/value pair in order for 
that pair to be used to control the keyboard input window. The shift state is one of: 

SHIFTDONTCARE 
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USER COMMANDS 



swttcher(I) 



FILES 

/usr/bin/switcher 
SEE ALSO 

suntools(l), shelltool(l), adjacentscreens(l) 
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USER COMMANDS 



SYMORDER ( 1 ) 



NAME 

symorder - rearrange name list 
SYNOPSIS 

symorder orderlist symbolfile 
DESCRIPTION 

orderlist is a file containing symbols to be found in symbolfile, 1 symbol per line. 

symbolfile is updated in place to put the requested symbols first in the symbol table, in the order specified. 
This is done by swapping the old symbols in the required spots with the new ones. If all of the order sym- 
bols are not found, an error is generated. 

This program was specifically designed to cut down on the overhead of getting symbols from /vmunix. 

SEE ALSO 

nlist(3) 
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GAMES AND DEMOS 



GRAPHICSDEMOS ( 6 ) 



NAME 

graphicsdemos, bouncedemo, cframedemo, framedemo, goban, jumpdemo, maze, shaded, show, 
showmap, spheresdemo, stringart, suncube - graphics demonstration programs 

SYNOPSIS 

bouncedemo [ -d dev ] [ -nx ] [ — r ] [ — cj ] 
cframedemo [ -d dev ] [ -nx ] [ — r ] [ — q ] 
framedemo [ -d dev ] [ -nx ] [ -r ] [ -q ] 
goban game 

jumpdemo [ -c ] [ -d dev ] [ -nx ] [ -r ] [ -q ] 

maze 

shaded object [ -d dev ] 
show rasterjile [ rasterfile ...] 
showmap [ -d dev ] [ -q ] 
spheresdemo [ -d dev ] [ -nx ] [ -r ] [ -q ] 
stringart [ -d dev ] [ — q ] 
suncube [ -d dev ] [ -q ] 

DESCRIPTION 

Note: Optional Software (Games and Demos Option). Refer to Installing UNIX on the Sun Workstation 

for information on how to install these demos. 

Bouncedemo 

bouncedemo displays a bouncing square. 

Cframedemo 

cframedemo displays a series of color frames, each of which contains a 256 by 256 image of eight-bit-deep 
pixels, (framedemo looks for the frames in the files framed through frame.n in the current working direc- 
tory, and displays them in numerical order. When run in the directory lusrl demo! globefr antes, cframedemo 
displays a rotating view of the world. 

Framedemo 

framedemo displays a series of frames, each of which contains a 256 by 256 image one-bit-deep pixels 
(that is, the image is a square monochrome bitmap, with 256 bits on a side), framedemo looks for the 
frames in the files frame. 1 through frame.n in the current working directory, and displays them in numeri- 
cal order. A set of sample frames is available in the directory lusrl demo! globefr ames! *. Interactive Com- 
mands 

If you move the cursor onto the image surface, you can type certain commands to affect the rate at which 
the frames are displayed. The initial rate is one frame per second: 

f removes l/20th of a second from the interval. 

F removes one second from the interval. Ff makes the interval as small as possible, 
s adds l/20th of a second. 

S adds one second. 

Goban 

goban is Japanese for "go board". It is an automatic board, but does not play go. If you invoke it with no 
game argument, goban displays an important historical game written about by the Nobel Prize winning 
author, Yasunari Kawabata in The Master of Go, a book which conveys the spirit of this ancient and 
facinating game. 
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GAMES AND DEMOS 



GR APHICS_DEMOS ( 6 ) 



Stones are placed on the board by selecting a grid point with the cursor and pressing the left-button. As 
stones are played, the color to play next alternates between black and white. The center-button, when 
pressed in the board area, backs up a move (undoes it). The right-button moves forward through the 
game’s sequence of moves. 

Stepping backward and forward does not alter the game until the left-button is pressed to place a stone, at 
which time a new branch in the line of play is begun. You can select branches by clicking the left button 
on moves with lettered labels on the board. 

A text subwindow displays any commentary attached to a move. You can edit these comments, which are 
saved along with the game. 

Jumpdemo 

jumpdemo simulates the famous Star Wars jump to light-speed-sequence using vector drawing. Colored 
stars are drawn on color surfaces. 

Maze 

maze creates a random maze-pattern and tries a depth-first solution. If used in lockscreen, remember to run 
in "nice" mode since this demo consumes lots of cpu cycles. 

Shaded 

shaded displays shaded objects. Objects are located in usrfdemolDATA and include an icosahedron, glass, 
soccer ball, space shuttle, egg and pyramid. This demo can take up to 40 seconds to start up with som 
objects. Mouse input is required: 

Interactive Commands 

Click the left- and middle-buttons on the left grid to set the x-y orientation. Click the middle-button on the 
right grid to set the z orientation. Click the left-button away from either grid to open the features menu, 
from which you can make selections using the left-button. 

After selecting the desired features, click the left-button away from all objects to exit the features menu. 

Click the right-button to begin drawing the object When the figure is finished, click the right-button to 
return to the grids and menu, or type q to exit. 

Show 

show displays rasterfiles in a window or on a raw screen. Sample files are contained in the directory 
lusrldemolCOLORPIX. Running 
show COLORPIX/* 

from fusrfdemo will continuously cycle through the sample images. 

Spheresdemo 

spheresdemo computes a random collection of shaded spheres. Colored spheres are drawn on color sur- 
faces. 

Showmap 

showmap displays 10 map projections continuously until interrupted. Each map is displayed for about 5 
seconds. The maps are in the directory lusr/demofMAPS. 

Stringart 

stringart continuously displays a different "work of art" every 5 seconds. A total of 24336 different 
designs are possible. On color surfaces the designs will loop through the colors: red, olive, green, tur- 
quoise, blue, and violet 

Suncube 

Displays a cube with the SUN logo mapped to each face. Will run continuously until interrupted. On color 
surfaces the colors of logo segments change gradually. On monochrome surfaces the logo segments 
remain hollow. 

OPTIONS 

-c Rotate the color map to produce a sparkling effect 
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-d surface 

Run the demo on a surface other than the window or system console, for instance: 
bouncedemo -d /dev/cgoneO 

-nx Draw x items, or repeat a sequence x times. 

-r Retain the window. This allows the image to reappear when uncovered instead of restarting the 

demo. 

-q Quick exit. Useful for running several demos from within a shell script 
SEE ALSO 

gp_demos(6), gfxtool(l) 
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LIFE (6) 



NAME 

life - John Conway’s game of life 

SYNOPSIS 

life 

DESCRIPTION 

Life is a program that plays John Conway’s game of life. It only runs under suntools( 1). 

When invoked, life will display a window with a small control panel at the top, and a large drawing area at 
the bottom. You can create pieces in the drawing area with the left button, and erase them with the middle 
button. When you select Run in the control panel, the pieces will begin to evolve, and the drawing region 
will update itself at a speed controlled by the slider labeled with Fast and Slow. Life keeps track of all the 
pieces even if they are not visible. The scroll bars surrounding the drawing region can be used to see 
pieces that have moved out of view. There are some standard patterns that can be drawn by popping up a 
menu in the drawing subwindow. 

The meaning of the items in the first row of the control panel (from left to right) are as follows. If you 
click on the picture which looks like a tic-tac-toe board, a grid will appear in the drawing region. If you 
click on Step, the mode will change from run mode (where the pieces update continuously) to step mode 
(where an update is only done when you click on Step). Following Gen is a number indicating the number 
of generations that have occured. The button marked Find will scroll so that at least one piece is in view. 
This is useful when all the pieces disappear from view. The button marked Clear will clear die drawing 
region, but leave the other controls unchanged. Reset will reset all the panel controls, but will not erase 
any of the pieces, and Quit causes the tool to exit. The second row contains two sliders. The first controls 
the update speed when in run mode, the second controls the size of the pieces. 
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NAME 

miscellaneous - miscellaneous useful information pages 
DESCRIPTION 

This section contains miscellaneous documentation, mostly in the area of text processing macro packages 



for troff{\). 




ascii(7) 


map of ASCII character set 


eqnchar(7) 


special character definitions for eqn 


hier(7) 


file system hierarchy 


man(7) 


macros to format manual pages 


me(7) 


macros for formatting papers 


ms(7) 


macros for formatting manuscripts 
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ASCII (7) 



NAME 

ascii - map of ASCII character set 

SYNOPSIS 

cat /usr/pub/ascil 

DESCRIPTION 

Ascii is a map of the ASCII character set, to be printed as needed. It contains: 
Decimal — Character 



1 o 


NUL 


■1 1 


SCH| 2 


STX| 3 


ETX| 4 


B0T| 5 


ENQ| 6 


ACK| 7 


BEL| 


1 8 


BS 


1 9 


HT 


1 io 


NL 


1 11 


VT 


1 12 


NP 


1 13 


CR 


1 14 


SO 


1 15 


SI | 


1 16 


DLE 


1 17 


DC1 


1 18 


DC2 


1 19 


DC3 


I 20 


DC4 


1 21 


NAK| 22 


SYN| 23 


ETB| 


1 24 


CAN 


r| 25 


EM 


I 26 


SUB 


| 27 


ESC 


| 28 


FS 


| 29 


GS 


| 30 


RS 


1 31 


US | 


| 32 


SP 


I 33 


r 


1 34 


ti 


| 35 


# 


| 36 


$ 


1 37 


% 


| 38 


& 


| 39 


' 1 


| 40 


( 


1 41 


) 


1 42 


* 


1 43 


+ 


| 44 


9 


1 45 


— 


| 46 


. 


1 47 


/ | 


1 48 


0 


| 49 


1 


1 50 


2 


1 51 


3 


1 52 


4 


| 53 


5 


1 54 


6 


| 55 


7 I 


| 56 


8 


1 57 


9 


| 58 


; 


1 59 


9 


| 60 


< 


1 61 


= 


| 62 


> 


1 63 


7 | 


| 64 


@ 


| 65 


A 


| 66 


B 


1 67 


C 


| 68 


D 


| 69 


E 


| 70 


F 


1 71 


G | 


| 72 


H 


| 73 


I 


1 74 


J 


1 75 


K 


1 76 


L 


| 77 


M 


| 78 


N 


| 79 


O | 


| 80 


P 


1 81 


Q 


| 82 


R 


| 83 


S 


1 84 


T 


| 85 


U 


| 86 


V 


| 87 


W 1 


| 88 


X 


| 89 


Y 


| 90 


Z 


1 91 


[ 


I 92 


\ 


I 93 


] 


| 94 


* 


1 95 


| 96 




| 97 


a 


| 98 


b 


| 99 


c 


|100 


d 


1101 


e 


1 102 


f 


|103 


g 1 


1104 


h 


1105 


i 


1106 


j 


1107 


k 


|108 


1 


1109 


m 


1 110 


n 


1111 


o | 


|U2 


P 


|113 


q 


|114 


r 


|115 


s 


1116 


t 


1117 


u 


|118 


V 


|119 


w | 


1120 


X 


|121 


y 


|122 


z 


|123 


{ 


|124 


1 


|125 


} 


|126 


- 


1127 


DEL| 


Octal - 


— C 


haracter 


























1000 


NX 


1001 


SCH 


[| 002 


SIX 


:|003 


EIX 


1004 


BOT 


|005 


ENQI006 


ACK|007 


BEL| 


1010 


BS 


ion 


HT 


1012 


NL 


1013 


VT 


|014 


NP 


|015 


CR 


1016 


SO 


|017 


SI | 


1020 


DLE 


1021 


DC1 


|022 


DC2 


1023 


DC3 


|024 


DC4 


1025 


NAK|026 


SYNI027 


ETB| 


1030 


CAN 


1031 


IM 


1032 


SUB 


1 033 


ESC 


|034 


FS 


|035 


GS 


1036 


RS 


1037 


US | 


1040 


SP 


|041 


i 


|042 


ft 


1043 


# 


|044 


$ 


|045 


% 


|046 


& 


1047 


' 1 


1050 


( 


|051 


) 


1052 


* 


1053 


+ 


1054 


9 


1055 


— 


1056 




|057 


/ | 


1060 


0 


1061 


1 


1062 


2 


1063 


3 


1064 


4 


1065 


5 


1066 


6 


1067 


7 I 


|070 


8 


|071 


9 


|072 


I 


|073 


J 


|074 


< 


1075 


ss 


|076 


> 


1077 


7 | 


1100 


@ 


|101 


A 


1102 


B 


1103 


C 


|104 


D 


1105 


E 


1 106 


F 


|107 


G | 


1110 


H 


1111 


I 


|112 


J 


|113 


K 


|114 


L 


|115 


M 


1 116 


N 


|117 


O | 


|120 


P 


1121 


Q 


|122 


R 


|123 


S 


|124 


T 


|125 


U 


|126 


V 


|127 


W | 


|130 


X 


1131 


Y 


1132 


Z 


1133 


[ 


1134 


\ 


1135 


] 


|136 


* 


1137 




|140 




|141 


a 


|142 


b 


1143 


c 


|144 


d 


|145 


e 


|146 


f 


1147 


g 1 


|150 


h 


|151 


i 


|152 


j 


1153 


k 


|154 


1 


1155 


m 


1 156 


n 


|157 


o | 


1160 


P 


1161 


q 


1162 


r 


1163 


s 


|164 


t 


|165 


u 


1166 


v 


|167 


w | 


|170 


X 


|171 


y 


|172 


z 


|173 


{ 


|174 


1 


|175 


} 


1 176 


- 


|177 


DEL| 
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TABLES 



Hexadecimal — Character 



00 NUL| 


01 


SCH| 


02 STX| 


03 EIX| 


04 BOT| 


05 ENQ| 


06 A£K | 


07 BEL 


08 BS | 


09 HT | 


OANL | 


OB VT | 


OCNP | 


CD (R | 


OE SO 


i 


OF SI 


10 DLE| 


11 DC1 1 


12 DC2| 


13 DC3 | 


14 DC4 1 


15 NAK| 


16 


SYN| 


17 ETB 


18 CAN| 


19 EM | 


1A SUB| 


IB ESC| 


1C FS | 


ID GS | 


IE RS 


i 


IF US 


20 SP | 


21 


! | 


22 


’ 1 


23 


# 1 


24 


$ 1 


25 


% 1 


26 


& 


i 


27 ' 


28 


( 1 


29 


) 1 


2A 


* 1 


2B 


+ | 


2C 


9 I 


2D 


- | 


2E 


. 


i 


2F 


/ 


30 0 | 


31 


1 | 


32 


2 I 


33 


3 1 


34 


4 I 


35 


5 I 


36 


6 


i 


37 


7 


38 


8 1 


39 


9 I 


3A 


: 1 


3B 


; 1 


3C 


< | 


3D 


= | 


3E 


> 


i 


3F 


? 


40 @ | 


41 


A | 


42 


B | 


43 


c | 


44 


D | 


45 


E | 


46 


F 


i 


47 G 


48 H | 


49 


I | 


4A 


J 1 


4B 


K | 


4C 


L | 


4D 


M | 


4E 


N 


i 


4F O 


50 P | 


51 


Q 1 


52 


R 1 


53 


S I 


54 


T | 


55 


U | 


56 


V 


i 


57 W 


58 X | 


59 


Y | 


5A 


Z | 


5B 


[ 1 


5C 


\ | 


5D 


] 1 


5E 


A 


i 


5F 


60 ' | 


61 


a 1 


62 


b 1 


63 


c 1 


64 


d | 


65 


e | 


66 


f 


i 


.67 g 


68 


h I 


69 


i 1 


6A 


j 1 


6B 


k | 


6C 


1 | 


6D 


m | 


6E 


n 


i 


6F o 


70 p | 


71 


q 1 


72 


r 1 


73 


s | 


74 


t 1 


75 


u | 


76 


V 


i 


77 w 


78 x | 


79 


y 1 


7A 


z 1 


7B 


{ 1 


7C 


1 1 


7D 


} 1 


7E 


" 


i 


7F EEL 



FILES 

/usr/pub/ascii 
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HIER(7) 


TABLES 


HffiR(7) 




/usr / preserve 


preserves editor files from crashes 




/usr/sccs 


sees programs 




/usr/ spool 


delayed execution files 




/usr/spool/znail 


system mailboxes 




/usr/spool/lpd 


printer queue(s) 




/usr/txnp 


temporary files 


SEE ALSO 


/usr/ucb 

/usr/ucb/Mail 
/usr/ucb/biff 
/usr/ucb/ccat 
/usr/ucb/ checknr 
/usr/ucb/ chsh 


programs developed at U.C. Berkeley 



ls(l), whatis(l), whereis(l), which(l), ncheck(8), find(l), grep(l) 

BUGS 

The position of files is subject to change without notice. 
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NAME 

man - macros to format Reference Manual pages 
SYNOPSIS 

nroff -man filename... 
troff -man filename... 

DESCRIPTION 

These macros are used to lay out the reference pages in this manual. 

Any text argument t may be zero to six words. Quotes may be used to include blanks in a ‘word’. If text is 
empty, the special treatment is applied to the next input line with text to be printed. In this way J may be 
used to italicize a whole line, or .SM followed by .B to make small bold letters. 

A prevailing indent distance is remembered between successive indented paragraphs, and is reset to default 
value upon reaching a non-indented paragraph. Default units for indents i are ens. 

Type font and size are reset to default values before each paragraph, and after processing font and size set- 
ting macros. 

These strings are predefined by -man: 

\*R ‘®\ ‘(Reg)’ in nroff. 

\*S Change to default type size. 

FILES 

/usr/lib/tmac/tmac.an 
SEE ALSO 

troff(l), nroff(l), man(l) 

The -man Macro Package, in Formatting Documents on the Sun Workstation. 



REQUESTS 

Request 


Cause If no 


Explanation 




Break 


Argument 


3t 


no 


t=n.Ll.* 


Text t is bold. 


.BI t 


no 


t=n.Ll. 


Join words of t alternating bold and italic. 


.BR t 


no 


t=n.tl. 


Join words of t alternating bold and Roman. 


JDT 


no 


.5i li... 


Restore default tabs. 


.HPz 


yes 


i=p.L* 


Set prevailing indent to i. Begin paragraph with hanging indent 


.It 


no 


t=n.tl. 


Text t is italic. 


.IB t 


no 


t=n.tL 


Join words of t alternating italic and bold. 


JPxi 


yes 


*="" 


Same as .TP with tag x. 


JR t 


no 


f=n.Ll. 


Join words of t alternating italic and Roman. 


UP 


yes 


- 


Same as .PP. 


JPDd 


no 


d=.4v 


Interparagraph distance is d. 


.PP 


yes 


- 


Begin paragraph. Set prevailing indent to .5i. 


.RE 


yes 


- 


End of relative indent. Set prevailing indent to amount of starting JIS. 


.RBf 


no 


t=n.tL 


Join words of t alternating Roman and bold. 


Hit 


no 


t=n.Ll 


Join words of t alternating Roman and italic. 


JRS i 


yes 


i=p.i. 


Start relative indent, move left margin in distance ». Set prevailing indent to .5i for 


.SHt 


yes 


t=n.tl. 


nested indents. 
Subhead. 


.SMt 


no 


t=n.tl. 


Text t is small. 


.TH n s dfm yes 


- 


Begin page named n of section s; d is the date of the most recent change. If present. 


.TP i 


yes 


i=p.i. 


/ is the left page footer; m is the main page (center) header. Sets prevailing indent 
and tabs to ,5i. 

Set prevailing indent to i. Begin indented paragraph with hanging tag given by next 
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text line. If tag doesn’t fit, place it on separate line. 

* n.Ll. = next text line; p.i. = prevailing indent 
CONVENTIONS 

A typical manual page for a command or function is laid out as follows: 

.TH TITLE [1-8] 

The name of the command or function in upper-case, which serves as the title of the manual page. 
This is followed by the number of the section in which it appears. 

.SH NAME name (or comma-separated list of names) - one-line summary 

The name, or list of names, by which the command is called, followed by a dash and then a one- 
line summary of die action performed. All in roman font, this section contains no troff(\) com- 
mands or escapes, and no macro requests. It is used to generate the whatis(l) database. 

.SH SYNOPSIS 

Commands: 

The syntax of the command and its arguments as typed on the command line. When in 
boldface, a word must be typed exactly as printed. When in italics, a word can be 
replaced with text that you supply. Syntactic symbols appear in roman face: 

[ ] An argument, when surrounded by brackets is optional. 

| Arguments separated by a vertical bar are exclusive. You can supply only item 

from such a list. 

Arguments followed by an elipsis can be repeated. When an elipsis follows a 
bracketed set, the expression within the brackets can be repeated. 

Functions: 

If required, the data declaration, or #include directive, is shown first, followed by the 
function declaration. Otherwise, the function declaration is shown. 

.SH DESCRIPTION 

A narrative description of the command or function in detail, including how it interacts with files 
or data, and how it handles the standard input, standard output and standard error. 

Filenames, and references to commands or functions described elswhere in the manual, are itali- 
cised. The names of options, variables and other literal terms are in boldface. 

.SH OPTIONS 

The list of options along with a description of how each affects the commands operation. 

.SH FILES 

A list of files associated with the command or function. 

.SH "SEE ALSO" 

A comma-separated list of related manual pages, followed by references to other published 
materials. This section contains no troff{ 1) escapes or commands, and no macro requests. 

.SH DIAGNOSTICS 

A list of diagnostic messages and an explanation of each. 

.SH BUGS 

A description of limitations, known defects, and possible problems associated with the command 
or function. 
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NAME 

me - macros for formatting papers 

SYNOPSIS 

nrolT -me [ options ] file ... 
troff -me [ options ] file ... 

DESCRIPTION 

This package of nr off and troff macro definitions provides a canned formatting facility for technical papers 
in various formats. When producing 2-column output on a terminal, filter the output through col{ 1). 

The macro requests are defined below. Many nroff and troff requests are unsafe in conjunction with this 
package, however these requests may be used with impunity after the first .pp: 

.bp begin new page 

.br break output line here 

.sp n insert n spacing lines 

,1s n (line spacing) n=l single, n=2 double space 

.na no alignment of right margin 

.ce n center next n lines 

.ul n underline next n lines 

.sz+n add n to point size 

Output of the eqn, neqn, refer , and tbl{ 1) preprocessors for equations and tables is acceptable as input 

FILES 

/usr/lib/tmac/tmac.e 

/usr/lib/me/* 

SEE ALSO 

eqn(l), nroff(l), troff(l), refer(l), tbl(l) 

The - me Macro Package , in Formatting Documents on the Sun Workstation . 

REQUESTS 

In the following list, “initialization” refers to the first .pp, .lp, .ip, .np, .sh, or .uh macro. This list is incom- 
plete; see The -me Reference Manual for interesting details. 



Request Initial Cause Explanation 
Value Break 



(C 


- 


yes 


Begin centered block 


•(d 


- 


no 


Begin delayed text 


•<f 


- 


no 


Begin footnote 


•d 


- 


yes 


Begin list 


(q 


- 


yes 


Begin major quote 


.(xx 


- 


no 


Begin indexed item in index x 


.(z 


- 


no 


Begin floating keep 


.)c 


- 


yes 


End centered block 


■)d 


- 


yes 


End delayed text 


•)f 


- 


yes 


End footnote 


•)1 


- 


yes 


End list 


•)q 


- 


yes 


End major quote 


•)x 


- 


yes 


End index item 


•)z 


- 


yes 


End floating keep 


.++ m H 




no 


Define paper section, m defines the part of the paper, and can be C (chapter), A (appen- 
dix), P (preliminary, e.g., abstract, table of contents, etc.), B (bibliography), RC (chapters 
renumbered from page one each chapter), or RA (appendix renumbered from page one). 


.+c T 


- 


yes 


Begin chapter (or appendix, etc., as set by .++). T is the chapter title. 


.lc 


1 


yes 


One column format on a new page. 


.2c 


1 


yes 


Two column format. 
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NAME 

dump, rdump - incremental file system dump 
SYNOPSIS 

/etc/dump [ options [ arguments ] ] filesystem 
DESCRIPTION 

Dump backs up all files in filesystem , or files changed after a certain date, to magnetic tape. Options is a 

string that specifies dump options, as shown below. Any arguments supplied for specific options are given 

as subsequent words on the command line, in the same order as that of die options listed. 

If no options are given, the default is 9u. 

OPTIONS 

0-9 The "dump level." All files in the filesystem that have been modified since the last dump at a 
lower dump level are copied to the tape. For instance, if you did a "level 2" dump on Monday, 
followed by a "level 4" dump on Tuesday, a subsequent "level 3" dump on Wednesday would 
contain all files modified or added since the "level 2" (Monday) backup. A "level 0" dump copies 
the entire filesystem to tape. 

b factor Blocking factor. Specifies the blocking factor for tape writes. The default is 10 blocks per write. 
Note that a tape block is 1024 bytes in size, or twice the size of a disk block. The highest blocking 
factor available with some 6250bpi tape drives is 126. 

c Cartridge. Use a cartridge instead of the standard half-inch reel. This sets the density to lOOObpi 
and the length to 1700 feet. When dumping to a high-density (9-track) cartridge, include the s 
(size) option with the 3825 (feet) argument to properly fill each cartridge. (This option is incom- 
patible with the d option, unless you specify a density of lOOObpi with that option). 

d bpi Tape density. The density of the tape, expressed in BPI, is taken from bpi. This is used to keep a 
running tab on the amount of tape used per reel. The default density is 1600. Unless a higher 
density is specified explicitly, dump uses its default density — even if the tape drive is capable of 
higher-density operation (for instance, 6250bpi). 

f dump-file 

Dump file. Use dump-file as the file to dump to, instead of /devfrmt8. If dump-file is specified as 
4 -\ dump to the standard output. If the filename argument is of the form machine . device, dump 
to a remote machine. Since dump is normally run by root, the name of the remote machine must 
appear in the .rhosts file of the local machine. If dump is called as rdump , the tape defaults to 
dumphost:/dev/rmt8. To direct the output to a desired remote machine, set up an alias for dum- 
phost in the file fete/ hosts. 

n Notify. When this option is specified, if dump requires attention, it sends a terminal message 
(similar to wall( 1)) to all operators in the "operator" group. 

s size Specify the size of the tape or cartridge in feet. When the specified size is reached, dump waits for 
you to change the reel or cartridge. The default size is 2300 feet, except when c (cartridge) is 
specified, in which case the default is 1700. To estimate the size for a tape or cartridge of a non- 
standard length, use the formula: 

(< length * tracks) * .9 

u Update the dump record. Add an entry to the file fetcfdumpdates, for each filesystem successfully 
dumped that includes the filesystem name, date, and dump level. This file can be edited by the 
super-user. 

w List the filesystems that need backing up. This information is gleaned from the files 
fetc/dumpdates and feteffstab . When the w option is used, all other options are ignored. After 
reporting, dump exits immediately. 

W Like w, but includes all filesystems that appear in fetc/dumpdates , along with information about 
their most recent dump dates and levels. Filesystems that need backing up are highlighted. 
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Operator Intervention 

dump requires operator intervention on these conditions: end of tape, end of dump, tape write error, tape 
open error or disk read error (if there are more than a threshold of 32). In addition to alerting all operators 
implied by the n option, dump interacts with the operator on dump’s control terminal at times when dump 
can no longer proceed, or if something is grossly wrong. All questions dump poses must be answered by 
typing "yes" or "no", as appropriate. 

Since backing up a disk can involve a lot of time and effort, dump checkpoints at the start of each tape 
volume. If writing that volume fails for some reason, dump will, with operator permission, restart itself 
from the checkpoint after a defective tape has been rewound and replaced. 

dump reports periodically, and in verbose fashion. Each report includes estimates of the percentage of the 
dump completed and how long it will take to complete the dump. 

Suggested Dump Schedule 

It is vital to perform full, "level 0", dumps at regular intervals. When performing a full dump, bring the 
machine down to single-user mode using shutdown (8). While preparing for a full dump, it is a good idea 
to clean the drive and heads. 



Incremental dumps allow for convenient backup and recovery on a more frequent basis of active files, with 
a minimum of tape and time. However there are some tradeoffs. First, the interval between backups should 
be kept to a minimum (once a day at least). To guard against data loss as a result of a media failure (a rare, 
but possible occurrence), it is a good idea to capture active files on (at least) two dump tapes. Another con- 
sideration is the desire to keep unnecessary duplication of files to a minimum to save both operator time 
and tape storage. A third consideration is the ease with which a particular backed-up version of a file can 
be located and restored. The following four-week schedule offers a reasonable tradeoff between these 
goals. 

Sun Mon Tue Wed Thu Fri 



Week 1 
Week 2. 
Week 3. 
Week 4. 



FuD 5 5 

5 5 

5 5 

5 5 



5 5 3 
5 5 3 
5 5 3 
5 5 3 



Although the Tuesday — Friday incrementals contain "extra copies" of files from Monday, this scheme 
assures that any file modified during the week can be recovered from the previous day’s incremental dump. 



FILES 

/devlrmt8 default tape unit to dump to 

/etcldumpdates new format dump date record 

letclfstab dump table: file systems and frequency 

I etc! group to find group operator 



SEE ALSO 

restore(8), dump(5), fstab(5) 

DIAGNOSTICS 

While running, dump emits many verbose messages. 

Exit Codes 

0 normal exit when w or W options are used. 

1 normal exit 

2 error - restart writing from last checkpoint 

3 abort - no checkpoint attempted. 

BUGS 

Sizes are based on 1600 BPI blocked tape; the raw tape device has to be used to approach these densities. 
Fewer than 32 read errors on the filesystem are ignored. 
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Each reel requires a new process, so parent processes for reels already written just hang around until the 
entire tape is written. 
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NAME 

dumpfs - dump file system information 
SYNOPSIS 

/usr/etc/dumpfs device 
DESCRIPTION 

Dumpfs prints out the super block and cylinder group information for the file system or special device 
specified. The listing is very long and detailed. This command is useful mostly for finding out certain file 
system information such as the file system block size and minimum free space percentage. 

SEE ALSO 

fs(5), tunefs(8), newfs(8), fsck(8) 
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NAME 

edquota - edit user quotas 
SYNOPSIS 

/usr/etc/edquota [ -p proto-user ] users. . . 

/usr/etc/edquota -t 

DESCRIPTION 

Edquota is a quota editor. One or more users may be specified on the command line. For each user a tem- 
porary file is created with an ASCII representation of the current disk quotas for that user and an editor is 
then invoked on the file. The quotas may then be modified, new quotas added, etc. Upon leaving the edi- 
tor, edquota reads the temporary file and modifies the binary quota files to reflect the changes made. 

The editor invoked is vi(l) unless the EDITOR environment variable specifies otherwise. 

Only the super-user may edit quotas. (In order for quotas to be estabished on a file system, the root direc- 
tory of the file system must contain a file, owned by root, called quotas. See quotaon( 1) for details.) 

OPTIONS 

-p duplicate the quotas of the prototypical user specified for each user specified. This is the normal 
mechanism used to initialize quotas for groups of users. 

-t edit the soft time limits for each file system. If the time limits are zero, the default time limits in 
<ufslquota.h> are used. Time units of sec(onds), min(utes), hour(s), day(s), week(s), and 
month(s) are understood. Time limits are printed in the greatest possible time unit such that the 
value is greater than or equal to one. 

FILES 

quotas quota file at the file system root 

/etc/mtab mounted file systems 

SEE ALSO 

quota(l), quotactl(2), quotacheck(8), quotaon(8), repquota(8) 

BUGS 

The format of the temporary file is inscrutible. 
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NAME 

fastboot, fasthalt - reboot/halt the system without checking the disks 
SYNOPSIS 

/etc/fastboot [ boot-options ] 

/etc/fasthalt [ halt-options ] 

DESCRIPTION 

fastboot and fasthalt are shell scripts that reboot and halt the system without checking the file systems. 
This is done by creating a file /fastboot, then invoking the reboot program. The system startup script, 
letclrc, looks for this file and, if present, skips the normal invocation of fsck(Z). 

SEE ALSO 

halt(8), init(8), rc(8), reboot(8) 
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NAME 

fingerd - remote user information server 

SYNOPSIS 

/usi7etc/in.fingerd 

DESCRIPTION 

fingerd is a simple protocol based on RFC742 that provides an interface to the Name and Finger programs 
at several network sites. The program is supposed to return a friendly, human-oriented status report on 
either the system at the moment or a particular person in depth. There is no required format and the proto- 
col consists mostly of specifying a single ‘‘command line”. 

fingerd listens for TCP requests at port 79. Once connected it reads a single command line terminated by a 
<CRLF> which is passed to finger (l). fingerd closes its connections as soon as the output is finished. 

If the line is null (i.e. just a <CRLF> is sent) then finger returns a “default” report that lists all people 
logged into the system at that moment. 

If a user name is specified (e.g. eric<CRLF>) then the response lists more extended information for only 
that particular user, whether logged in or not. Allowable “names” in the command line include both 
“login names” and “user names”. If a name is ambiguous, all possible derivations are returned. 

SEE ALSO 

finger(l) 

BUGS 

Connecting directly to the server from a TIP or an equally narrow-minded TELNET-protocol user program 
can result in meaningless attempts at option negotiation being sent to the server, which will foul up the 
command line interpretation, fingerd should be taught to filter out IAC’s and perhaps even respond nega- 
tively (IAC WON’T) to all option commands received. 
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NAME 

fparel - Sun FPA online reliability tests 

SYNOPSIS 

fparel [ -pn ] [ -v ] 

DESCRIPTION 

fparel is a command to execute the Sun FPA online confidence and reliability test program, fparel tests 
about 90% of the functions of the FPA board, and tests all FPA contexts not in use by other processes. 
fparel runs under UNIX without disturbing other processes that may be using the FPA. fparel can only be 
run by the super-user. 

After a successful pass, fparel writes 

time, date: Sun FPA Passed. The contexts tested are: 0, 1, ... 31 
to the file lusr/adm/diaglog. 

If a pass fails, fparel writes 

time, date: Sun FPA failed 

along with the test name and context number that failed, to the file lusrladmldiaglog. fparel then broadcasts 
the message 

time, date: Sun FPA failed, disabled, service required 

to all users of the system. Next, fparel causes the kernel to disable the FPA. Once the kernel disables the 
FPA, the system must be rebooted to make it accessible. 

The file /etc/rc.local should contain an entry to cause fparel to be invoked upon reboot to be sure that the 
FPA remains unaccessible in cases where rebooting doesn’t correct the problem. See ic(8). 

lusrlliblcrontab should contain an entry indicating that cron(8) is to run fparel daily, such as: 

12*** /usr/etc/fpa/fparel 

which causes fparel to run at seven minutes past two, every day. See cron (8) and crontab( 5) for details. 
OPTIONS 

-pn Perform n passes. Default is n=l. -pO means perform 2147483647 passes. 

-v Run in verbose mode with detailed test results to standard output. 

FILES 

lusrladmldiaglog Log of fparel diagnostics. 
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NAME 

iostat - report I/O statistics 
SYNOPSIS 

iostat [ interval [ count ] ] 

DESCRIPTION 

Iostat iteratively reports the number of characters read and written to terminals, and, for each disk, the 
number of seeks and transfers per second, and the milliseconds per average seek. It also gives the percen- 
tage of time the system has spent in user mode, in user mode running low priority (niced) processes, in sys- 
tem mode, and idling. 

To compute this information, for each disk, seeks and data transfer completions and number of words 
transferred are counted; for terminals collectively, the number of input and output characters are counted. 
Also, each fiftieth of a second, the state of each disk is examined and a tally is made if the disk is active. 
From these numbers and given the transfer rates of the devices it is possible to determine average seek 
times for each device. 

The optional interval argument causes iostat to report once each interval seconds. The first report is for all 
time since a reboot and each subsequent report is for the last interval only. 

The optional count argument restricts the number of reports. 

FILES 

/dev/kmem 

/vmunix 

SEE ALSO 

vmstat(8) 
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NAME 

kadb - adb-like kernel and standalone-program debugger 
SYNOPSIS 

> b kadb [ — d ] [ boot-flags ] 

DESCRIPTION 

kadb is an interactive debugger that is similar in operation to adb( 1), and runs as a standalone program 
under the PROM monitor. You can use kadb to debug the UNIX kernel, or to debug any standalone pro- 
gram. 

Unlike adb, kadb runs in the same supervisor virtual address space as the program being debugged — 
although it maintains a separate context. The debugger runs as a coprocess that cannot be killed (no :k) or 
rerun (no :r). There is no signal control (no :i, :t, or $i), although the UNIX keyboard facilities CC,~S and 
*Q) are simulated. 

While the kernel is running under kadb , the abort sequence (Ll-A or BREAK) causes UNIX to drop into kadb 
for debugging — as will a system panic. When running other standalone programs under kadb , the abort 
sequence will pass control to the PROM monitor, kadb is then invoked from the monitor by jumping to the 
starting address for kadb found in <debugldebug.h> (currently this can be done for both Sun-2 and Sun-3 
machines with the monitor command g fdOOOOO). kadb’s user interface is similar to adb . Note that kadb 
prompts with 

kadb> 

Most adb commands function in kadb as expected. Typing an abort sequence in response to the prompt 
returns you to the PROM monitor, from which you can examine control spaces that aren’t accessible within 
adb or kadb. The PROM monitor command c will return control to kadb. As with “adb -k”, $p works 
when debugging UNIX kernels (by actually mapping in new user pages). The verbs ? and / are equivalent 
in kadb , since there is only one address space in use. 

OPTIONS 

kadb is booted from the PROM monitor as a standalone program. If you omit the -d flag, kadb automati- 
cally loads and runs vmunix from the filesystem kadb was loaded from. The kadb “vmunix” variable can 
be patched to change the default program to be loaded. 

-d Interactive startup. Prompts with 

kadb: 

for a file to be loaded. >From here, you can enter a boot sequence line to load a standalone pro- 
gram. Boot flags entered in response to this prompt are included with those already set and passed 
to the program. If you type a carriage return only, kadb loads vmunix from the filesystem that 
kadb was loaded from. 

boot-flags 

You can specify boot flags as arguments when invoking kadb. Note that kadb always sets the -d 
(debug) boot flag, and passes it to the program being debugged. 

USAGE 

Refer to adb in Program Debugging Tools for the Sun Workstation . 

Kernel Macros 

As with adb , kernel macros 2 re supported. With kadb , however, the macros are compiled into the 
debugger itself, rather than being read in from the filesystem. The kadb command $M lists macros known 
to kadb. 

Setting Breakpoints 

Self-relocating programs such as the Sun-3 kernel need to be relocated before breakpoints can be used. To 
set the first breakpoint for such a program, start it with :s; kadb is then entered after the program is relo- 
cated (when UNIX initializes its interrupt vectors). Thereafter, :s single-steps as with adb. Otherwise, use 
:c to start up the program. 
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Automatic Rebooting with Kadb 

You can set up your workstation to automatically reboot kadb by patching the “vmunix” variable in /boot 
with the string “kadb” instead of “vmunix”. (Refer to adb in Program Debugging Tools for the Sun 
Workstation for details on how to patch executables.) 

Kadb on a Diskless Workstation 

If your workstation is set up to boot over the network from a partition other than pubO , then you should 
patch the short kadb variable “ndbootdev” to be “0x0”, for the private nd partition, or “0x41”, for the 
publ nd partition. This will insure that the file to be debugged and kadb come from the same nd filesystem. 

If “ndbootdev” is not patched, then you must be explicit when booting with kadb. Use the command 

> b kadb -d 

so that kadb will prompt for the program to be debugged At the prompt use the commmand 
kadb: device( , , p)JUename 

where p is “0x1” for the publ nd partition or “0x40” for the private nd partition. Note that these values 
for p (partition) will work if the file to be debugged is in the same filesystem as kadb. 

FILES 

/vmunix 

/boot 

/kadb 

/usr/include/debug/debug.h 

SEE ALSO 

adb( 1), boot(&S) 

Program Debugging Tools for the Sun Workstation 
Writing Device Drivers for the Sun Workstation 

BUGS 

There is no floating-point support 

kadb cannot reliably single-step over instructions that change the status register. 

When sharing the keyboard with UNIX the monitor’s input routines can leave the keyboard in a confued 
state. If this should happen, disconnect the keybooard momentarily and then reconnect it This forces the 
keyboard to reset as well as initiating an abort sequence. 

Most of the bugs listed in adb{ 1) also apply to kadb . 
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NAME 

kgmon - generate a dump of the operating system’s profile buffers 
SYNOPSIS 

/usr /etc/ kgmon [ -b ] [ -h ] [ -r ] [ -p ] [ system ] [ memory ] 

DESCRIPTION 

Kgmon is a tool used when profiling the operating system. When no arguments are supplied, kgmon indi- 
cates the state of operating system profiling as running, off, or not configured (see config(%)). If the -p flag 
is specified, kgmon extracts profile data from the operating system and produces a gmon.out file suitable for 
later analysis by gprof( 1). 

OPTIONS 

-b Resume the collection of profile data. 

-h Stop the collection of profile data. 

— p Dump the contents of the profile buffers into a gmon.out file. 

— r Reset all the profile buffers. If the — p flag is also specified, the gmon.out file is generated before 

the buffers are reset 

If neither -b nor -h is specified, the state of profiling collection remains unchanged. For example, if the 
— p flag is specified and profile data is being collected, profiling is momentarily suspended, the operating 
system profile buffers are dumped, and profiling is immediately resumed. 

FILES 

/vmunix - the default system 
/dev/kmem - the default memory 

SEE ALSO 

gprof (1), config(8) 

DIAGNOSTICS 

Users with only read permission on /dev/kmem cannot change the state of profiling collection. They can 
get a gmon.out file with the warning that the data may be inconsistent if profiling is in progress. 
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ks,sk select keyboard for input and screen for output 

[AB]# set speed of serial port A (or B) to # (such as 1200,9600,..) 

e echo input to output 

ne don’t echo input to output 

u addr set virtual serial port address to addr . 

If no serial port is specified when changing speeds, the current input device is changed. 

At power-up, the following default settings are used: the default console input device is the Sun 
keyboard or if the keyboard is unavailable, serial port A. The default console output device is the 
Sun screen or if the graphics board is unavailable, serial port A. All serial ports are set to 9600 
Baud. 

V addrl addr2 [size] Sun 3 only 

display the contents of addresses from (lower) addrl to (higher) address addr2 in the format 
specified by size : 

b byte format (the default), 

w word format, or 

1 long word format 

Enter return to pause for viewing; enter another return character resume the display. To 
terminate the display at any time, press the space bar. Or, you can use A S and A Q to stop 
and start the display. 

For example, the following command displays the contents of virtual address space from 
address 0x1000 to 0x2000 in word format: 

V 1000 2000 W 

W [addr ] [arg ] Sun 3 only. 

Vector to addr. arg is one of: 

print prints the contents of virtual address addr as a string, 
dump initiates a crash dump, 
trace produces a stack trace. 

X Sun 3 only 

display a menu of extended tests to be presented, with loop and print options also selectable. 
These test commands are provided to permit additional testing of such things as the I/O port con- 
nectors at the handle edge of the CPU board. Video memory, workstation memory and the works- 
tation keyboard, as well as permit the boot device paths to be tested. 

Z [addr] Sun 3 only. 

set a breakpoint at addr in the address space selected by the S command. 
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NAME 

mount, umount - mount and dismount filesystems 

SYNOPSIS 

/etc/mount [ -p ] 

/etc/mount — a[fv] [ — t type ] 

/etc/mount [ — frv ] [ — t type ] [ — o options ] fsname dir 
/etc/mount [ -vf ] [ — o options] fsname | dir 

/etc/umount [ -t type ] [ -h host ] 

/etc/umount -a[v] 

/etc/umount [ -v ] 

DESCRIPTION 

mount announces to the system that a filesystem fsname is to be attached to the file tree at the directory dir. 
The directory dir must already exist It becomes the name of the newly mounted root. The contents of dir 
are hidden until the filesystem is unmounted. If fsname is of the form host:path the filesystem type is 
assumed to be nfs. 

umount announces to the system that the filesystem fsname previously mounted on directory dir should be 
removed. Either the filesystem name or the mounted-on directory may be used. 

mount and umount maintain a table of mounted filesystems in /etc/mtab, described in mtab(5). If invoked 
without an argument, mount displays the table. If invoked with only one of fsname or dir mount searches 
the file letclfstab (see fstab( 5)) for an entry whose dir or fsname field matches the given argument For 
example, if this line is in letclfstab: 

/dev/xyOg /usr 4.2 rw 1 1 

then the commands mount /usr and mount /dev/xyOg are shorthand for mount /dev/xyOg /usr 
MOUNT OPTIONS 

-p Print the list of mounted filesystems in a format suitable for use in letclfstab. 

-a Attempt to mount all the filesystems described in letclfstab. (In this case, fsname and dir are taken 
from letclfstab.) If a type is specified all of the filesystems in letclfstab with that type is mounted. 
Filesystems are not necessarily mounted in the order listed in letclfstab . 

-f Fake a new letc/mtab entry, but do not actually mount any filesystems. 

-v Verbose — mount displays a message indicating the filesystem being mounted. 

-t The next argument is the filesystem type. The accepted types are: 4.2, and nfs; see fstab{ 5) for a 
description of these filesystem types. 

-r Mount the specified filesystem read-only. This is a shorthand for: 
mount — o ro fsname dir 

Physically write-protected and magnetic tape filesystems must be mounted read-only, or errors 
occur when access times are updated, whether or not any explicit write is attempted. 

-o Specify options , a list of comma seperated words from the list below. Some options are valid for 
all filesystem types, while others apply to a specific type only. 

options valid on all file systems (the default is rw,suid): 

rw read/write. 

ro read-only. 

suid set-uid execution allowed. 

nosuid set-uid execution not allowed. 

noauto do not mount this file system automatically (mount -a). 
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options specific to 4.2 file systems (the default is noquota), 
quota usage limits enforced, 

noquota usage limits not enforced. 

options specific to nfs (NFS) file systems (the defaults are: 

fg,retry=10000,timeo=7,retrans=3,port=NFS_PORT,hard 
with defaults for rsize and wsize set by the kernel): 
bg if the first mount attempt fails, retry in the background, 

fg retry in foreground. 

retry=n set number times to retry mount to n. 
rsize=n set read buffer size to n bytes, 
wsiz e=/i set write buffer size to n bytes. 

timeo=n set NFS timeout to n tenths of a second. 
retrans=n set number of NFS retransmissions to n. 
port=n set server IP port number to n. 

soft return error if server doesn’t respond, 

hard retry request until server responds, 

intr allow keyboard interrupts on hard mounts. 

The bg option causes mount to run in the background if the server’s mountd(%) does not respond. 
mount attempts each request retry=n times before giving up. Once the filesystem is mounted, 
each NFS request made in the kernel waits timeo =n tenths of a second for a response. If no 
response arrives, the time-out is multiplied by 2 and the request is retransmitted. When retrans=/i 
retransmissions have been sent with no reply a soft mounted filesystem returns an error on the 
request and a hard mounted filesystem prints a message and retries the request. Filesystems that 
are mounted rw (read-write) should use the hard option. The intr option allows keyboard inter- 
rupts to kill a process that is hung waiting for a response on a hard mounted filesystem. The 
number of bytes in a read or write request can be set with the rsize and wsize options. 

UMOUNT OPTIONS 

-h host Unmount all filesystems listed in letcfmtab that are remote-mounted from host. 

-a Attempt to unmount all the filesystems currently mounted (listed in letclmtab). In this case, 
fsname is taken from letclmtab. 

— v Verbose — umount displays a message indicating the filesystem being unmounted. 

EXAMPLES 

mount /dev/xyOg /usr mount a local disk 

mount -ft 4.2 /dev/ndO / fake an entry for nd root 

mount -at 4.2 mount all 4.2 filesystems 

mount -t nfs serv:/usr/src /usr/src mount remote filesystem 

mount serv:/usr/src /usr/src same as above 

mount -o hard serv:/usr/src /usr/src same as above but hard mount 

mount -p > /ete/fstab save current mount state 

FILES 

/etc/mtab table of mounted filesystems 

/etc/fstab table of filesystems mounted at boot 



Sun Release 3.4 



Last change: 13 January 1987 



635 




M0UNT(8) 



MAINTENANCE COMMANDS 



MOUNT (8) 



SEE ALSO 

mount(2), unmount(2), fstab(S), mountd(8C), nfsd(8C) 

BUGS 

Mounting filesystems full of garbage crashes the system. 

No more than one ND client should mount an ND disk partition "read-write" or the file system may 
become corrupted. 

If the directory on which a filesystem is to be mounted is a symbolic link, the filesystem is mounted on the 
directory to which the symbolic link refers, rather than being mounted on top of the symbolic link itself. 
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NAME 

setup - Sun UNIX installation program 

SYNOPSIS 

setup 

DESCRIPTION 

setup is the program supplied by Sun to install major Sun Unix releases such as 2.0 or 3.0. setup allows a 
system administrator to install major Sun Unix release on new hardware, upgrade between major releases, 
and add additional hardware to existing machines. 

setup provide both a tty interface for cursor addressable terminals and a SunWindows system interface for 
use on bit mapped displays. The Setup Reference Manual contains a detailed description of the use of 
setup . 

Initially, setup asks the following questions in a menu format before entering the tty or SunWindows inter- 
face. For all menus respond to the » prompt with the corresponding number of the menu item you choose. 

The first question asked is the mode of use of setup. 

Are you running setup: 

1) to install on a new system 

2) re-entrantly 

3) to upgrade an existing system 

4) in demonstration mode 

» 

The next question is to determine the type of interface to be used. Note that the cursor addressable inter- 
face can be used within a shelltool{\) under SunWindows. 

Will you be running setup from: 

1) a Sun bit mapped display device 

2) a cursor addressable terminal 

» 

If you have selected the tty interface for cursor addressable terminals, setup asks for the terminal type. 
Select your terminal type: 

1) Televideo 925 

2) Wyse Model 50 

3) Sun Workstation 

4) Other 

» 

If you select "Other", the name of the terminal must correspond to a name in the termcap( 5) database. 

Enter the terminal type (your terminal type must be in /etc/termcap) 

» 

setup begins running the interface for the terminal-type you have selected. 

FILES 

fetclhosts 

/etclnd. local 

/etclethers 

letcfrc.local 

letcfrc.boot 

! etc! setup. info 

lusrlliblsendmail.cf 

BUGS 

setup will not run on tty devices that do not support cursor addressing and are not registered in the 
termcap( 5) data base. 
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NAME 

showmount - show all remote mounts 
SYNOPSIS 

/usr/etc/showmount [ -a ] [ -d ] [ -e ] [ host ] 

DESCRIPTION 

Showmount lists all the clients that have remotely mounted a filesystem from host . This information is 
maintained by the mountd{%C) server on host, and is saved across crashes in the file letclrmtab. The 
default value for host is the value returned by hostname( 1). 

OPTIONS 

-d List directories that have been remotely mounted by clients. 

-a Print all remote mounts in the format 
hostname:directory 

where hostname is the name of the client, and directory is the root of the file system that has been 
mounted. 

-e Print the list of exported file systems. 

SEE ALSO 

rmtab(5), mountd(8), exports(5) 

BUGS 

If a client crashes, its entry will not be removed from the list until it reboots and executes umount -a. 
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NAME 

statd - network status monitor 

SYNOPSIS 

/etc/rpc.statd 

DESCRIPTION 

Statd is an intermediate version of the status monitor. It interacts with lockd{ 8c) to provide the crash and 
recovery functions for the locking services on NFS. 

FILES 

/ etc! statmonl current 
letc/statmon/backup 
I etc! statmonl state 

SEE ALSO 

lockd(8C), statmon(5) 

BUGS 

The crash of a site is only detected upon its recovery. 
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NAME 

sticky - executable files with persistent text 
DESCRIPTION 

While the ‘sticky bit’, mode 01000 (see chmod( 2)), is set on a sharable executable file, the text of that file 
will not be removed from the system swap area. Thus the file does not have to be fetched from the file sys- 
tem upon each execution. As long as a copy remains in the swap area, the original text cannot be overwrit- 
ten in the file system, nor can the file be deleted. Directory entries can be removed so long as one link 
remains. 

Sharable files are made by the -z option of M( 1). 

To replace a sticky file that has been used; 

1. Clear the sticky bit with chmod(W). 

2. Execute the old program to flush the swapped copy. This can be done safely even if others are 
using it. 

3. Overwrite the sticky file. If the file is being executed by any process, writing will be prevented; it 
suffices to simply remove the file and then rewrite it, being careful to reset the owner and mode 
with chmod and chown(2). 

4. Set the sticky bit once again, if still needed. 

A directory for which the ‘sticky bit’ is set restricts deletion of files it contains. A file in a sticky directory 
may only be removed or renamed by a user who has write permission on the directory, and either owns the 
file, owns the directory, or is the super-user. This is useful for directories such as limp, which must be pub- 
licly writable, but which should deny users access to arbitrarily delete or rename the files of others. 

Any user may create a sticky directory. Only the super-user can set the sticky bit on a non-directory file. 
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NAME 

chmod, fchmod - change mode of file 
SYNOPSIS 

#include /usr/include/sys/stat.h 

chmod(path, mode) 
char *path; 
int mode; 

fchmod(fd, mode) 
int fd, mode; 



DESCMPTION 

The file whose name is given by path or referenced by the descriptor fd has its mode changed to mode. 
Modes are constructed by or ’ ing together some combination of the following: 



S_ISUID 

S_ISGID 

S_ISVTX 

SJREAD 

SIWRITE 

S EXEC 



04000 set user ID on execution 

02000 set group ID on execution 

01000 save text image after execution (sticky bit) 

00400 read by owner 

00200 write by owner 

00100 execute (search on directory) by owner 
00070 read, write, execute (search) by group 
00007 read, write, execute (search) by others 



These bit patterns are defined in /usr/include/sys/stat.h. 



The effective user ID of the process must match the owner of the file or be super-user to change the mode 
of a file. 



If the effective user ID of the process is not super-user and the process attempts to set the set group ID bit 
on a file owned by a group which is not in its group access list, mode bit 02000 (set group ID on execution) 
is cleared. 



If an executable file is set up for sharing (this is the default) then mode 01000 (save text image after execu- 
tion) prevents the system from abandoning the swap-space image of the program-text portion of the file 
when its last user terminates. If this mode is set on a directory, an unprivileged user may not delete or 
rename files of other users in that directory. If the effective user ID of the process is not super-user and the 
object is not a directory, this bit is cleared. 

If a user other than the super-user writes to a file, the set user ID and set group ID bits are turned off. This 
makes the system somewhat more secure by protecting set-user-DD (set-group-ID) files from remaining 
set-user-ID (set-group-ID) if they are modified, at the expense of a degree of compatibility. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of-1 is returned and errno is set 
to indicate the error. 



ERRORS 

chmod will fail and the file mode will be unchanged if: 

ENOTDIR A component of the path prefix of path is not a directory. 

EIN V AL path contains a byte with the high-order bit set 

ENAMETOOLONG 

The length of a component of path exceeds 255 characters, or the length of path exceeds 
1023 characters. 

ENOENT The file referred to by path does not exist. 

EACCES Search permission is denied for a component of the path prefix of path. 
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ELOOP Too many symbolic links were encountered in translating path . 

EPERM The effective user ID does not match the owner of the file and the effective user ED is 

not the super-user. 

EINVAL fd refers to a socket, not to a file. 

EROFS The file referred to by path resides on a read-only file system. 

EFAULT path points outside the process’s allocated address space. 

EIO An I/O error occurred while reading from or writing to the file system. 

fchmod will fail if: 

EBADF The descriptor is not valid. 

EROFS The file referred to by fd resides on a read-only file system. 

EPERM The effective user ID does not match the owner of the file and the effective user ID is 

not the super-user. 

EIO An I/O error occurred while reading from or writing to the file system. 

FILES 

/usr/include/sys/stath 
SEE ALSO 

open(2V), chown(2), stat(2), sticky(8) 
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NAME 

getrlimit, setrlimit - control maximum system resource consumption 



SYNOPSIS 

#include <sys/time.h> 

#include <sys/resource.h> 

getrlimit(resource, rip) 
int resource; 
struct rlimit *rlp; 

setrlimit(resource, rip) 
int resource; 
struct rlimit *rlp; 

DESCRIPTION 

Limits on the consumption of system resources by the current process and each process it creates may be 
obtained with the getrlimit call, and set with the setrlimit call. 



The resource parameter is one of the following: 



RLIMIT _CPU 
RLIMIT_FSIZE 
RLIMIT J)ATA 

RLIMITSTACK 

RLIMITCORE 

RLIMITJtSS 



the maximum amount of cpu time (in seconds) to be used by each process. 

the largest size, in bytes, of any single file that may be created. 

the maximum size, in bytes, of the data segment for a process; this defines how far a 
program may extend its break with the sbrk( 2) system call. 

the maximum size, in bytes, of the stack segment for a process; this defines how far a 
program’s stack segment may be extended automatically by the system. 

the largest size, in bytes, of a core file that may be created. 

the maximum size, in bytes, to which a process’s resident set size may grow. This 
imposes a limit on the amount of physical memory to be given to a process; if 
memory is tight, the system will prefer to take memory from processes that are 
exceeding their declared resident set size. 



A resource limit is specified as a soft limit and a hard limit. When a soft limit is exceeded a process may 
receive a signal (for example, if the cpu time is exceeded), but it will be allowed to continue execution until 
it reaches the hard limit (or modifies its resource limit). The rlimit structure is used to specify the hard and 
soft limits on a resource, 



struct rlimit { 

int rlimcur; /* current (soft) limit */ 

int rlim max; /* hard limit */ 

}; 

Only the super-user may raise the maximum limits. Other users may only alter rlimjcur within the range 
from 0 to rlimjnax or (irreversibly) lower rlimjnax . 

An “infinite” value for a limit is defined as RLIM_INFINITY (0x7fffffff). 

Because this information is stored in the per-process information, this system call must be executed directly 
by the shell if it is to affect all future processes created by the shell; limit is thus a built-in command to 
csh( 1). 

The system refuses to extend the data or stack space when the limits would be exceeded in the normal way: 
a brk or sbrk call will fail if the data space limit is reached, or the process will be killed when the stack 
limit is reached (since the stack cannot be extended, there is no way to send a signal!). 

A file I/O operation which would create a file that is too large will cause a signal SIGXFSZ to be gen- 
erated; this normally terminates the process, but may be caught. When the soft CPU time limit is exceeded, 
a signal SIGXCPU is sent to the offending process. 
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RETURN VALUE 

A 0 return value indicates that the call succeeded, changing or returning the resource limit. A return value 
of -1 indicates that an error occurred, and an error code is stored in the global location errno. 

ERRORS 

The possible errors are: 

EFAULT The address specified for rip is invalid. 

EINVAL An invalid resource was specified; or in a setrlimit call, the new rlim_cur exceeds the 

new rlimjnax. 

EFERM The limit specified to setrlimit would have raised the maximum limit value, and the 

caller is not the super-user. 

SEE ALSO 

csh(l), quota(2) 

BUGS 

There should be limit and unlimit commands in jA( 1) as well as in csh. 
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NAME 

gettimeofday, settimeofday - get or set the date and time 
SYNOPSIS 

#include <sys/time Ji> 

gettimeofday(tp, tzp) 
struct timeval *tp; 
struct timezone *tzp; 

settimeofday(tp, tzp) 
struct timeval *tp; 
struct timezone *tzp; 

DESCRIPTION 

The system’s notion of the current Greenwich time and the current time zone is obtained with the get- 
timeofday call, and set with settimeofday. The current time is expressed in elapsed seconds and 
microseconds since, January 1, 1970 (zero hour). The resolution of the system clock is hardware depen- 
dent; the time may be updated continuously, or in “ticks.” 

The structures pointed to by tp and tzp are defined in <sys!time.h> as: 

struct timeval { 

long tvsec; /* seconds since Jan. 1, 1970 */ 

long tv usec; I* and microseconds */ 

}; 



struct timezone { 

int tz_minuteswest; /* of Greenwich */ 

int tz_dsttime; /* type of dst correction to apply */ 

}; 

The timezone structure indicates the local time zone (measured in minutes westward from Greenwich), and 
flag that indicates the type of Daylight Saving Time correction to apply. Note that this flag does not indi- 
cate whether DST is currently in effect. 

If tzp is a zero pointer, the timezone information is not returned or set. 

Only the super-user may set the time of day or the time zone. 

RETURN 

A -1 return value indicates an error occurred; in this case an error code is stored in the global variable 
errno . Other return codes indicate the type of Daylight Savings Time currently in effect (as defined in 
/ usr/includelsysltime.h ): 

0 DSTNONE: Daylight Savings Time not observed 

1 DSTJUSA: United States DST 

2 DST_AUST: Australian DST 

3 DST WET: Western European DST 

4 DST_MET: Middle European DST 

5 DSTEET: Eastern European DST 

6 DST CAN: Canadian DST 

7 DST GB: Great Britian and Eire DST 

8 DST RUM: Rumanian DST 

9 DST TUR: Turkish DST 

10 DSTAUSTALT: Australian-style DST with shift in 1986 

ERRORS 

The following error codes may be set in errno: 

EFAULT An argument address referenced invalid memory. 
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EPERM A user other than the super-user attempted to set the time. 

SEE ALSO 

date(l), adjtime(2), ctime(3) 

BUGS 

Time is never correct enough to believe the microsecond values. There should a mechanism by which, at 
least, local clusters of systems might synchronize their clocks to millisecond granularity. 

Daylight Savings Time correction tables aren’t guaranteed to be correct for specific locales. 
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NAME 

getuid, geteuid - get user identity 

SYNOPSIS 

uid = getuidO 
int uid; 

euid = geteuidO 
int euid; 

DESCRIPTION 

Getuid returns the real user ID of the current process, geteuid the effective user ID. 

The real user ID identifies the person who is logged in. The effective user ID gives the process additional 
permissions during execution of “set-user-ID” mode processes, which use getuid to determine the real- 
user-id of the process that invoked them. 

SEE ALSO 

getgid(2), setreuid(2) 
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NAME 

read, readv - read input 
SYNOPSIS 

cc = read(d, buf, nbytes) 
int cc, d; 
char *buf; 
int nbytes; 

#include <sys/types.h> 

#include <sys/uio.h> 

cc = readv(d, iov, iovcnt) 
int cc, d; 
struct iovec *iov; 
int iovcnt; 

DESCRIPTION 

read attempts to read nbytes of data from the object referenced by the descriptor d into the buffer pointed to 
by buf. readv performs the same action, but scatters the input data into the iovcnt buffers specified by the 
members of the iov array: iov[0], iov[l], iov[iovcnt- 1]. 

For readv, the iovec structure is defined as 

struct iovec { 

caddrjt iov_base; 
int iov_len; 

}; 

Each iovec entry specifies the base address and length of an area in memory where data should be placed. 
readv will always fill an area completely before proceeding to the next 

On objects capable of seeking, the read starts at a position given by the pointer associated with d (see 
lseek( 2)). Upon return from read, the pointer is incremented by the number of bytes actually read. 

Objects that are not capable of seeking always read from the current position. The value of the pointer 
associated with such an object is undefined. 

Upon successful completion, read and readv return the number of bytes actually read and placed in the 
buffer. The system guarantees to read the number of bytes requested if the descriptor references a normal 
file which has that many bytes left before the end-of-file, but in no other case. 

If the returned value is 0, then end-of-file has been reached. 

When attempting to read from a descriptor associated with an empty pipe, socket, or FIFO: 

If ONDELAY is set, the read will return a -1 and err no will be set to EWOULDBLOCK. 

If 0_NDELAY is clear, the read will block until data is written to the pipe or the file is no longer 
open for writing. 

When attempting to read from a descriptor associated with a tty that has no data currently available: 

If O NDELAY is set, the read will return a —1 and errno will be set to EWOULDBLOCK. 

If O NDELAY is clear, the read will block until data becomes available. 

If O NDELAY is set, and less data are available than are requested by the read or readv, only the data that 
are available are returned, and the count indicates how many bytes of data were actually read. 

SYSTEM V DESCRIPTION 

When an attempt is made to read a descriptor which is in no-delay mode, and there is no data currently 
available, read will return a 0 instead of returning a -1 and setting errno to EWOULDBLOCK. Note that this 
is indistinguishable from end-of-file. 
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RETURN VALUE 

If successful, the number of bytes actually read is returned. Otherwise, a -1 is returned and the global vari- 
able errno is set to indicate the error. 

ERRORS 

read and readv will fail if one or more of the following are true: 

EB ADF d is not a valid file descriptor open for reading. 

EISDIR d refers to a directory which is on a file system mounted using die NFS. 

EFAULT buf points outside the allocated address space. 

EIO An I/O error occurred while reading from or writing to the file system. 

EINTR A read from a slow device was interrupted before any data arrived by the delivery of a 

signal. 

EINV AL The pointer associated with d was negative. 

EWOULDBLOCK 

The file was marked for non-blocking I/O, and no data were ready to be read. In addi- 
tion, readv may return one of the following errors: 

EINVAL Iovcnt was less than or equal to 0, or greater than 16. 

EINVAL One of the iovjen values in the iov array was negative. 

EINVAL The sum of the iovjen values in the iov array overflowed a 32-bit integer. 

EFAULT Part of iov points outside the process’ s allocated address space. 

SEE ALSO 

dup(2), fcnd(2), open(2), pipe(2), select(2), socket(2), socketpair(2) 
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RETURN VALUE 

Upon successful completion, a non-negative integer, namely a shared memory identifier is returned. Other- 
wise, a value of -1 is returned and errno is set to indicate the error. 



SEE ALSO 

intro(2), shmctl(2), shmop(2) 
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NAME 

shmop, shmat shmdt - shared memory operations 
SYNOPSIS 

#htclude <sys/types.h> 

#include <sys/ipc.h> 
finclude <sys/shm.h> 

char *shmat (shmid, shmaddr, shmflg) 
int shmid; 
char * shmaddr 
int shmflg; 

int shmdt (shmaddr) 
char *shmaddr 



DESCRIPTION 

shmat attaches the shared memory segment associated with the shared memory identifier specified by 
shmid to the data segment of the calling process. The segment is attached at the address specified by one of 
the following criteria: 

If shmaddr is equal to zero, the segment is attached at the first available address as selected by the 
system. 

If shmaddr is not equal to zero and (shmflg & SHMJRND) is “true”, the segment is attached at 
the address given by (shmaddr - (shmaddr modulus SHMLBA)). 

If shmaddr is not equal to zero and (shmflg & SHM_RND) is “false”, the segment is attached at 
the address given by shmaddr. 

The segment is attached for reading if (shmflg & SHM_RDONLY) is “true” {READ}, otherwise it is 
attached for reading and writing {READ/WRITE}. 

shmdt detaches from the calling process’s data segment the shared memory segment located at the address 
specified by shmaddr. 



ERRORS 

shmat will fail and not attach the shared memory segment if one or more of the following are true: 

EINV AL Shmid is not a valid shared memory identifier. 

EACCES Operation permission is denied to the calling process (see intro(2)). 

ENOMEM The available data space is not large enough to accommodate the shared memory seg- 
ment. 



EINVAL shmaddr is not equal to zero, and the value of (shmaddr - (shmaddr modulus 

SHMLBA)) is an illegal address. 

EINVAL shmaddr is not equal to zero, (shmflg & SHM_RND) is “false”, and the value of 

shmaddr is an illegal address. 

EMFILE The number of shared memory segments attached to the calling process would exceed 

the system-imposed limit. 

shmdt will fail and not detach the shared memory segment if: 

EINVAL shmaddr is not the data segment start address of a shared memory segment 
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RETURN VALUES 

Upon successful completion, the return value is as follows: 

shmat returns the data segment start address of the attached shared memory segment. 
shmdt returns a value of 0. 

Otherwise, a value of -1 is returned and err no is set to indicate the error. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), shmctl(2), shmget(2). 
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NAME 

shutdown - shut down part of a full-duplex connection 

SYNOPSIS 

shutdowns, how) 
int s, how; 

DESCRIPTION 

The shutdown call causes all or part of a full-duplex connection on the socket associated with 5 to be shut 
down. If how is 0, then further receives will be disallowed. If how is 1, then further sends will be disal- 
lowed. If how is 2, then further sends and receives will be disallowed. 

DIAGNOSTICS 

A 0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 

EBADF S is not a valid descriptor. 

ENOTSOCK 5 is a file, not a socket 

ENOTCONN The specified socket is not connected. 

SEE ALSO 

connect(2), socket(2) 

BUGS 

The how values should be defined constants. 
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NAME 

socket - create an endpoint for communication 



SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

s = socket(af, type, protocol) 
int s, af, type, protocol; 

DESCRIPTION 

Socket creates an endpoint for communication and returns a descriptor. 

The of parameter specifies an address format with which addresses specified in later operations using the 
socket should be interpreted. These formats are defined in the include file < sy si socket. h> . The currently 
understood formats are 



AFUNIX 
AFJNET 
AFPUP 
AF IMPLINK 



(UNIX path names), 

(ARPA Internet addresses), 

(Xerox PUP-I Internet addresses), and 
(IMP “host at IMP” addresses). 



The socket has the indicated type which specifies the semantics of communication. Currently defined types 
are: 



SOCKSTREAM 

SOCKDGRAM 

SOCKRAW 

SOCKSEQPACKET 

SOCKJRDM 

A SOCK STREAM type provides sequenced, reliable, two-way connection based byte streams with an 
out-of-band data transmission mechanism. A SOCK DGRAM socket supports datagrams (connectionless, 
unreliable messages of a fixed (typically small) maximum length). SOCK RAW sockets provide access to 
internal network interfaces. The types SOCK RAW, which is available only to the super-user, and 
SOCK SEQPACKET and SOCK RDM, which are planned, but not yet implemented, are not described 
here. 

The protocol specifies a particular protocol to be used with the socket Normally only a single protocol 
exists to support a particular socket type using a given address format However, it is possible that many 
protocols may exist in which case a particular protocol must be specified in this manner. The protocol 
number to use is particular to the “communication domain” in which communication is to take place; see 
services (5) and protocols^ 5). 

Sockets of type SOCK STREAM are full-duplex byte streams, similar to pipes. A stream socket must be 
in a connected state before any data may be sent or received on it. A connection to another socket is 
created with a connect (2) call. Once connected, data may be transferred using read{ 2V) and write {2V) 
calls or some variant of the send(2) and recv(2) calls. When a session has been completed a close (2) may 
be performed. Out-of-band data may also be transmitted as described in send (2) and received as described 
in recv(2). 

The communications protocols used to implement a SOCK_STREAM insure that data is not lost or dupli- 
cated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted 
within a reasonable length of time, then the connection is considered broken and calls will indicate an error 
with -1 returns and with ETIMEDOUT as the specific code in the global variable ermo. The protocols 
optionally keep sockets “warm” by forcing transmissions roughly every minute in the absence of other 
activity. An error is then indicated if no response can be elicited on an otherwise idle connection for a 
extended period (e.g. 5 minutes). A SIGPIPE signal is raised if a process sends on a broken stream; this 
causes naive processes, which do not handle the signal, to exit 
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SOCKDGRAM and SOCK RAW sockets allow sending of datagrams to correspondents named in 
send( 2) calls. It is also possible to receive datagrams at such a socket with recv( 2). 

An fcntl (2) call can be used to specify a process group to receive a SIGURG signal when the out-of-band 
data arrives. 



The operation of sockets is controlled by socket level options. These options are defined in the file 
<sys/ socket. h> and explained below. Setsockopt and getsockopt(2) are used to set and get options, respec- 
tively. 



SO_DEBUG 
SOREUSE ADDR 
SOKEEP ALIVE 
SODONTROUTE 
SO_LINGER 
SO_DONTLINGER 



turn on receding of debugging information 

allow local address reuse 

keep connections alive 

do no apply routing on outgoing messages 

linger on close if data present 

do not linger on close 



SO DEBUG enables debugging in the underlying protocol modules. SO REUSEADDR indicates the 
rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. 
SOKEEPALIVE enables the periodic transmission of messages on a connected socket. Should the con- 
nected party fail to respond to these messages, the connection is considered broken and processes using the 
socket are notified via a SIGPIPE signal. SO_DONTROUTE indicates that outgoing messages should 
bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface 
according to the network portion of the destination address. SOLINGER and SO DONTLINGER control 
the actions taken when unsent messags are queued on socket and a close( 2) is performed. If the socket 
promises reliable delivery of data and SO_LINGER is set, the system will block the process on the close 
attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a 
timeout period, termed the linger interval, is specified in the setsockopt call when SO LINGER is 
requested). If SO_DONTLINGER is specified and a close is issued, the system will process the close in a 
manner which allows the process to continue as quickly as possible. 



RETURN VALUE 

A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket 
ERRORS 

The socket call fails if: 



EAFNOSUPPORT The specified address family is not supported in this version of the system. 
ESOCKTN OSUPPORT 

The specified socket type is not supported in this address family. 

EPROTONOSUPPORT 

The specified protocol is not supported. 

EMFILE The per-process descriptor table is full. 

ENOBUFS No buffer space is available. The socket cannot be created. 

EPROTOTYPE The protocol is die wrong type for the socket. 

SEE ALSO 

accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), iocd(2), listen(2), recv(2), select(2), 
send(2), shutdown(2), socketpair(2) 

Inter-Process Communication Primer in Networking on the Sun Workstation 

BUGS 

The use of keepalives is a questionable feature for this layer. 
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NAME 

frexp, ldexp, modf- floating point analysis and synthesis 
SYNOPSIS 

double frexp(value, eptr) 
double value; 
int *eptr; 

double Idexp(value, exp) 
double value; 
int exp; 

double modf(value, iptr) 
double value, *iptr; 

DESCRIPTION 

Frexp returns the significand of a double value as a double quantity, x, of magnitude less than 1 and stores 
an integer n, indirectly through eptr, such that value = x*2 n . 

The results are not defined when value is an IEEE infinity or NaN. 

ldexp returns the quantity: 

value * 

modf returns the fractional part of value and stores the integral part indirectly through iptr. Thus the argu- 
ment value and the returned values modf and *iptr satisfy, in the absence of rounding error, 

(*iptr + modf) == value 

and 



0 <= abs{modf) < abs(value). 

The signs of *iptr and modf are the same as the signs of value. The results are not defined when value is an 
IEEE infinity or NaN. 

Since Sun’s definition of modf conforms to the System V Interface Definition and the VAX 4.2BSD imple- 
mentation but differs from the 4.2BSD documentation, results vary from some other Unix implementations 
whose modf conforms to the 4.2BSD documentation but not the VAX 4.2BSD implementation. Therefore 
avoid modf in code intended to be portable. 

SEE ALSO 

floor(3m) 
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NAME 

ftok - standard interprocess communication package 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

key_t ftok(path, id) 
char *path; 
char id; 

DESCRIPTION 

All interprocess communication facilities require the user to supply a key to be used by the msgget( 2), 
semget{ 2), and shmget( 2) system calls to obtain interprocess communication identifiers. One suggested 
method for forming a key is to use the ftok subroutine described below. Another way to compose keys is to 
include the project ID in the most significant byte and to use the remaining portion as a sequence number. 
There are many other ways to form keys, but it is necessary for each system to define standards for faming 
them. If some standard is not adhered to, it will be possible for unrelated processes to unintentionally inter- 
fere with each other’s operation. Therefore, it is strongly suggested that the most significant byte of a key 
in some sense refer to a project so that keys do not conflict across a given system. 

ftok returns a key based on path and id that is usable in subsequent msgget, semget, and shmget system 
calls, path must be the path name of an existing file that is accessible to the process, id is a character 
which uniquely identifies a project Note that ftok will return the same key for linked files when called with 
the same id and that it will return different keys when called with the same file name but different ids. 

SEE ALSO 

intro(2), msgget(2), semget(2), shmget(2) 

DIAGNOSTICS 

ftok returns (key_t) —1 if path does not exist or if it is not accessible to the process. 

WARNING 

If the file whose path is passed to ftok is removed when keys still refer to the file, future calls to ftok with 
the same path and id will return an error. If the same file is recreated, then ftok is likely to return a dif- 
ferent key than it did the original time it was called. 
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NAME 

utime - set file times 
SYNOPSIS 

#include <sys/types.h> 

utime(file, timep) 
char 

time_t timep[2]; 

DESCRIPTION 

The utime call uses the ‘accessed’ and ‘updated’ times in that order from the timep vector to set the 
corresponding recorded times for file . 

The caller must be the owner of the file or the super-user. The ‘inode-changed’ time of the file is set to the 
current time. 

SEE ALSO 

utimes(2), stat(2) 
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NAME 

vlimit - control maximum system resource consumption 



SYNOPSIS 

#indude <sys/vlimit.h> 

vlimit (resource, value) int resource, value; 



DESCRIPTION 

This facility is superseded by getrlimit(2). 



Limits the consumption by the current process and each process it creates to not individually exceed value 
on the specified resource. If value is specified as -1, then the current limit is returned and the limit is 
unchanged. The resources which are currently controllable are: 



LEVf_NORAISE A pseudo-limit; if set non-zero then the limits may not be raised. Only the super-user 
may remove the noraise restriction. 

LIM CPU the maximum number of cpu-seconds to be used by each process 

LIM FSIZE the largest single file which can be created 

LIM_DATA die maximum growth of the data+stack region via sbrk( 2) beyond the end of the pro- 
gram text 

L1M_STACK the maximum size of the automatically-extended stack region 

LIM CORE die size of the largest core dump that will be created. 

LIM_MAXRSS a soft limit for die amount of physical memory (in bytes) to be given to the program. If 
memory is tight, the system will prefer to take memory from processes which are 
exceeding their declared LIM MAXRSS. 



Because this information is stored in the per-process information this system call must be executed directly 
by the shell if it is to affect all future processes created by the shell; limit is thus a built-in command to 
csA(l). 



The system refuses to extend the data or stack space when the limits would be exceeded in the normal way; 
a break call fails if the data space limit is reached, or the process is killed when the stack limit is reached 
(since the stack cannot be extended, there is no way to send a signal!). 

A file i/o operation which would create a file which is too large will cause a signal SIGXFSZ to be gen- 
erated, this normally terminates the process, but may be caught. When the cpu time limit is exceeded, a 
signal SIGXCPU is sent to the offending process; to allow it time to process the signal it is given 5 seconds 
grace by raising the cpu time limit 



SEE ALSO 

csh(l) 



BUGS 

If LIM NORAISE is set, then no grace should be given when the cpu time limit is exceeded. 
There should be limit and unlimit commands in sh (1) as well as in csh. 
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NAME 

fopen, freopen, fdopen - open a stream 

SYNOPSIS 

#inciude <stdio.h> 

FILE *fopen(filename, type) 
char ^filename, *type; 

FILE *freopen(filename, type, stream) 
char *filename, ♦type; 

FILE ^stream; 

FILE * fdopen (fildes, type) 
char *type; 

DESCRIPTION 

fopen opens the file named by filename and associates a stream with it. If the open succeeds, fopen returns 
a pointer to be used to identify the stream in subsequent operations. 

filename points to a character string that contains the name of the file to be opened. 
type is a character string having one of the following values: 

"r" open for reading 

"w" truncate or create for writing 

"a” append: open for writing at end of file, or create for writing 

"r+" open for update (reading and writing) 

"w+" truncate or create for update 

"a+" append; open or create for update at end-of-file 

freopen opens the file named by filename and associates the stream pointed to by stream with it. The type 
argument is used just as in fopen. The original stream is closed, regardless of whether the open ultimately 
succeeds. If the open succeeds, freopen returns the original value of stream. 

freopen is typically used to attach the preopened streams associated with stdin, stdout, and stderr to other 
files. 

fdopen associates a stream with a file descriptor. File descriptors are obtained from calls like open, dup , 
creat, or pipe (2), which open files but do not return streams. Streams are necessary input for many of the 
Section 3S library routines. The type of the stream must agree with the mode of the open file. 

When a file is opened for update, both input and output may be done on the resulting stream. However, 
output may not be directly followed by input without an intervening/^* or rewind , and input may not be 
directly followed by output without an intervening fseek, rewind , or an input operation which encounters 
end-of-file. 

SEE ALSO 

open(2V), fclose(3S), fseek(3S), fopen(3V) 

DIAGNOSTICS 

fopen, freopen, and fdopen return a NULL pointer on failure. 

BUGS 

In order to support the same number of open files as the system does, fopen must allocate additional 
memory for data structures using calloc after 30 files have been opened. This confuses some programs 
which use their own memory allocators. 
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NAME 

fread, fwrite - buffered binary input/output 

SYNOPSIS 

#include <stdio.h> 

fread(ptr, size, nitems, stream) 

FILE ^stream; 

fwrite(ptr, size, nitems, stream) 

FILE ^stream; 

DESCRIPTION 

fread reads, into a block pointed to by ptr, nitems of data from the named input stream, where an item of 
data is a sequence of bytes (not necessarily terminated by a null byte) of length size. It returns the number 
of items actually read, fread stops appending bytes if an end-of-file or error condition is encountered while 
reading stream, or if nitems items have been read, fread leaves the file pointer in stream, if defined, point- 
ing to the byte following the last byte read if there is one. fread does not change the contents of stream. 

If die standard output is line-buffered, fread flushes its output before reading from the standard input. This 
is also true for the standard error. 

fwrite appends at most nitems of data from die block pointed to by ptr to the named output stream. It 
returns the number of items actually written, fwrite stops appending when it has appended nitems items of 
data or if an error condition is encountered on stream, fwrite does not change the contents of the block 
pointed to by ptr. 

The argument size is typically sizeof(*ptr) where the pseudo-function sizeof specifies the length of an item 
pointed to by ptr. If ptr points to a data type other than char it should be cast into a pointer to char. 

If size or nitems is non-positive, no characters are read or written and 0 is returned by both fread and 

fwrite. 

SEE ALSO 

read(2V), write(2V), fopen(3S), gete(3S), putc(3S), gets(3S), puts(3S), printf(3S), scanf(3S), fread(3V) 
DIAGNOSTICS 

fread and fwrite return 0 upon end of file or error. 
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NAME 

puts, fputs - put a string on a stream 

SYNOPSIS 

#include <stdio.h> 

puts(s) 
char *s; 

fputs(s, stream) 
char *s; 

FILE ‘stream; 

DESCRIPTION 

puts writes the null-terminated string pointed to by s, followed by a newline character, to the standard out- 
put stream stdout 

fputs writes the null-terminated string pointed to by s to the named output stream. 

Neither function writes the terminal null character. 

DIAGNOSTICS 

Both routines return EOF on error. This will happen if the routines try to write on a file that has not been 
opened for writing. 

SEE ALSO 

fopen(3S), pute(3S), printf(3S), ferror(3S), fread(3S) 

NOTES 

puts appends a newline while does not 
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NAME 

scanf, fscanf, sscanf - formatted input conversion 

SYNOPSIS 

#include <stdio.h> 

scanf(format [, pointer ] . . . ) 
char ^format; 

fscanf(stream, format [, pointer ] . . . ) 

FILE “stream; 
char "•format; 

sscanf(s, format [, pointer ] . . . ) 
char *s, “format; 

DESCRIPTION 

scanf reads from the standard input stream stdin. fscanf reads from die named input stream, sscanf reads 
from the character string s. Each function reads characters, interprets them according to a format, and 
stores the results in its arguments. Each expects, as arguments, a control string format, described below, 
and a set of pointer arguments indicating where the converted input should be stored. 

The control string usually contains conversion specifications, which are used to direct interpretation of 
input sequences. The control string may contain: 

1. White-space characters (blanks, tabs, or new-lines) which, except in two cases described below, cause 
input to be read up to the next non-white-space character. 

2. An ordinary character (not %), which must match the next character of the input stream. 

3. Conversion specifications, consisting of the character %, an optional assignment suppressing character 
*, an optional numerical maximum field width, an optional 1 (ell) or h indicating the size of the receiv- 
ing variable, and a conversion code. 

A conversion specification directs the conversion of the next input field; the result is placed in the variable 
pointed to by the corresponding argument, unless assignment suppression was indicated by *. The 
suppression of assignment provides a way of describing an input field which is to be skipped. An input 
field is defined as a string of non-space characters; it extends to the next inappropriate character or until the 
field width, if specified, is exhausted. For all descriptors except “[” and “c”, white space leading an input 
field is ignored. 

The conversion character indicates the interpretation of the input field; the corresponding pointer argument 
must usually be of a restricted type. For a suppressed field, no pointer argument is given. The following 
conversion characters are legal: 

% a single % is expected in the input at this point; no assignment is done, 
d a decimal integer is expected; the corresponding argument should be an integer pointer, 

u an unsigned decimal integer is expected; the corresponding argument should be an unsigned 

integer pointer. 

o an octal integer is expected; the corresponding argument should be a integer pointer, 
x a hexadecimal integer is expected; the corresponding argument should be an integer pointer. 
e,f,g a floating point number is expected; the next field is converted accordingly and stored through the 
corresponding argument, which should be a pointer to a float. The input format for floating point 
numbers is an optionally signed string of digits, possibly containing a decimal point, followed by 
an optional exponent field consisting of an E or e followed by an optional +, -, or space, followed 
by an integer. 

s a character string is expected; the corresponding argument should be a character pointer pointing 

to an array of characters large enough to accept the string and a terminating \0, which will be 
added automatically. The input field is terminated by a white space character, 
c a character is expected; the corresponding argument should be a character pointer. The normal 
skip over white space is suppressed in this case; to read the next non-space character, use %ls. If 
a field width is given, the corresponding argument should refer to a character array, and the indi- 
cated number of characters is read. 
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[ indicates string data; the normal skip over leading white space is suppressed. The left bracket is 
followed by a set of characters, which we will call die scanset, and a right bracket; the input field 
is the maximal sequence of input characters consisting entirely of characters in the scanset. The 
circumflex ( * ), when it appears as the first character in the scanset, serves as a complement opera- 
tor and redefines the scanset as the set of all characters not contained in the remainder of the scan- 
set string. There are some conventions used in the construction of the scanset. A range of charac- 
ters may be represented by the construct first-last, thus [0123456789] may be expressed [0-9]. 
Using this convention, first must be lexically less than or equal to last, or else the dash will stand 
for itself. The dash will also stand for itself whenever it is the first or the last character in the 
scanset To include the right square bracket as an element of the scanset it must appear as the 
first character (possibly preceded by a circumflex) of the scanset and in this case it will not be 
syntactically interpreted as the closing bracket The corresponding argument must point to a char- 
acter array large enough to hold the data field and the terminating \0, which will be added 
automatically. At least one character must match for this conversion to be considered successful. 

The conversion characters d, u, o, and x may be capitalized or preceded by 1 or h to indicate that a pointer 
to long or to short rather than to int is in the argument list Similarly, the conversion characters e, f, and g 
may be preceded by 1 to indicate that a pointer to double rather than to float is in the argument list The 1 or 
h modifier is ignored for other conversion characters. 

scarf conversion terminates at EOF, at the end of the control string, or when an input character conflicts 
with the control string. In the latter case, the offending character is left unread in the input stream. 

scanf returns the number of successfully matched and assigned input items; this number can be zero in the 
event of an early conflict between an input character and the control string. 

If the input ends before the first conflict or conversion, EOF is returned. If the input ends after the first 
conflict or conversion, the number of successfully matched items is returned. 

EXAMPLES 

The call: 



int i, n; float x; char name[50]; 
n = scanf ("%d%f%s", &i, &x, name); 

with the input line: 

25 54.32E-1 thompson 

will assign to n the value 3, to i the value 25, to x the value 5.432, and name will contain thompson\0. On 

int i; float x; char name[50]; 

(void) scanf ("%2d%f%*d %[0-9]", &i, &x, name); 

with input 

56789 0123 56a72 

will assign 56 to i, 789.0 to x, skip 0123, and place the string 56\0 in name. The next call to getchar (see 
getc (3S)) will return a. 

SEE ALSO 

getc(3S), printf(3S) strtod(3), strtol(3), scanf(3V) 

DIAGNOSTICS 

These functions return EOF on end of input, and a short count for missing or illegal data items. 

BUGS 

The success of literal matches and suppressed assignments is not directly determinable. 

scarf cannot read the strings which printfQS) generates for IEEE indeterminate floating point values. 
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scarf provides no way to convert a number in any arbitrary base (decimal, hex or octal) based on the tradi- 
tional C conventions (leading 0 or Ox). 
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NAME 

setbuf, setbuffer, setlinebuf, setvbuf - assign buffering to a stream 

SYNOPSIS 

#include <stdioJh> 

setbuf(stream, buf) 

FILE ^stream; 
char *buf; 

setbuffer(stream, buf, size) 

FILE ^stream; 
char *buf; 
int size; 

setlinebuf(stream) 

FILE ^stream; 

int setvbuf (stream, buf, type, size) 

FILE ^stream; 
char *buf; 
int type, size; 

DESCRIPTION 

The three types of buffering available are unbuffered, block buffered, and line buffered. When an output 
stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is 
block buffered many characters are saved up and written as a block; when it is line buffered characters are 
saved up until a newline is encountered or input is read from stdin. /flush (see /close (3S)) may be used to 
force the block out early. Normally all files are block buffered. A buffer is obtained from malloc( 3) upon 
the first getc or putc (3S) on the file. If the standard stream stdout refers to a terminal it is line buffered. If 
the standard stream stderr refers to a terminal it is line buffered. 

setbuf can be used after a stream has been opened but before it is read or written. It causes the array 
pointed to by buf to be used instead of an automatically allocated buffer. If buf is the NULL pointer, 
input/output will be completely unbuffered. A manifest constant BUFSIZ, defined in the <stdloJi> header 
file, tells how big an array is needed: 

char buf[BUFSIZ]; 

setbuffer, an alternate form of setbuf, can be used after a stream has been opened but before it is read or 
written. It causes the character array buf whose size is determined by the size argument to be used instead 
of an automatically allocated buffer. If buf is the NULL pointer, input/output will be completely unbuf- 
fered. 

setvbuf can be used after a stream has been opened but before it is read or written, type determines how 
stream will be buffered. Legal values for type (defined in <stdio.h>) are: 

IOFBF causes input/output to be fully buffered. 

IOLBF causes output to be line buffered; the buffer will be flushed when a newline is written, the 
buffer is full, or input is requested. 

_IONBF causes input/output to be completely unbuffered. If buf is not the NULL pointer, the array it 
points to will be used for buffering, instead of an automatically allocated buffer. Size 
specifies the size of the buffer to be used. 

setlinebuf is used to change the buffering on a stream from block buffered or unbuffered to line buffered. 
Unlike setbuf, setbuffer, and setvbuf, it can be used at any time that the file descriptor is active. 

A file can be changed from unbuffered or line buffered to block buffered by using /reopen (seefopen(5S)). 
A file can be changed from block buffered or line buffered to unbuffered by using freopen followed by set- 
buf with a buffer argument of NULL. 
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STANDARD I/O LIBRARY 



SETBUF(3S) 



SEE ALSO 

fopen(3S), getc(3S), putc(3S), malloc(3), fclose(3S), puts(3S), printf(3S), fread(3S), setbuf(3V) 
DIAGNOSTICS 

If an illegal value for type or size is provided, setvbuf returns a non-zero value. Otherwise, the value 
returned will be zero. 



NOTE 

A common source of error is allocating buffer space as an “automatic” variable in a code block, and then 
failing to close the stream in the same block. 
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NAME 

scanf, fscanf, sscanf - formatted input conversion 

SYNOPSIS 

#include <stdio.h> 

scanf(format [, pointer ] . . . ) 
char 'format; 

fscanf(stream, format [, pointer ] . . . ) 

FILE 'stream; 
char 'format; 

sscanf(s, format [, pointer ] . . . ) 
char *s, 'format; 

DESCRIPTION 

scanf reads from the standard input stream stdin. fscanf reads from the named input stream, sscanf reads 
from the character string s. Each function reads characters, interprets them according to a format, and 
stores the results in its arguments . Each expects, as arguments, a control string format, described below, 
and a set of pointer arguments indicating where the converted input should be stored. 

The control string usually contains conversion specifications, which are used to direct interpretation of 
input sequences. The control string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form-feeds) which, except in two cases described 
below, cause input to be read up to the next non-white-space character. 

2. An ordinary character (not %), which must match the next character of the input stream. 

3. Conversion specifications, consisting of the character %, an optional assignment suppressing character 
*, an optional numerical maximum field width, an optional 1 (ell) or h indicating the size of the receiv- 
ing variable, and a conversion code. 

A conversion specification directs the conversion of the next input field; the result is placed in the variable 
pointed to by the corresponding argument, unless assignment suppression was indicated by *. The 
suppression of assignment provides a way of describing an input field which is to be skipped. An input 
field is defined as a string of non-space characters; it extends to the next inappropriate character or until the 
field width, if specified, is exhausted. For all descriptors except “[” and “c”, white space leading an input 
field is ignored. 

The conversion character indicates the interpretation of the input field; the corresponding pointer argument 
must usually be of a restricted type. For a suppressed field, no pointer argument is given. The following 
conversion characters are legal: 

% a single % is expected in the input at this point; no assignment is done, 
d a decimal integer is expected; the corresponding argument should be an integer pointer, 

u an unsigned decimal integer is expected; the corresponding argument should be an unsigned 

integer pointer. 

o an octal integer is expected; the corresponding argument should be a integer pointer, 
x a hexadecimal integer is expected; the corresponding argument should be an integer pointer. 
e,f,g a floating point number is expected; the next field is converted accordingly and stored through the 
corresponding argument, which should be a pointer to a float. The input format for floating point 
numbers is an optionally signed string of digits, possibly containing a decimal point, followed by 
an optional exponent field consisting of an E or e followed by an optional +, -, or space, followed 
by an integer. 

s a character string is expected; the corresponding argument should be a character pointer pointing 
to an array of characters large enough to accept the string and a terminating \0, which will be 
added automatically. The input field is terminated by a white space character, 
c a character is expected; the corresponding argument should be a character pointer. The normal 
skip over white space is suppressed in this case; to read the next non-space character, use %ls. If 
a field width is given, the corresponding argument should refer to a character array, and the indi- 
cated number of characters is read. 
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[ indicates string data; the normal skip over leading white space is suppressed. The left bracket is 
followed by a set of characters, which we will call the scanset, and a right bracket; the input field 
is the maximal sequence of input characters consisting entirely of characters in the scanset. The 
circumflex ( * ), when it appears as the first character in the scanset, serves as a complement opera- 
tor and redefines the scanset as the set of all characters not contained in the remainder of the scan- 
set string. There are some conventions used in the construction of the scanset. A range of charac- 
ters may be represented by the construct first-last, thus [0123456789] may be expressed [0-9]. 
Using this convention, first must be lexically less than or equal to last, or else the dash will stand 
for itself. The dash will also stand for itself whenever it is the first or the last character in the 
scanset To include the right square bracket as an element of the scanset it must appear as the 
first character (possibly preceded by a circumflex) of the scanset and in this case it will not be 
syntactically interpreted as the closing bracket. The corresponding argument must point to a char- 
acter array large enough to hold the data field and the terminating \0, which will be added 
automatically. At least one character must match for this conversion to be considered successful. 

The conversion characters d, u, o, and x may be capitalized or preceded by 1 or h to indicate that a pointer 
to long or to short rather than to int is in the argument list Similarly, the conversion characters e, f, and g 
may be preceded by 1 to indicate that a pointer to double rather than to float is in the argument list The 1 or 
h modifier is ignored for other conversion characters. 

scarf conversion terminates at EOF, at the end of the control string, or when an input character conflicts 
with the control string. In the latter case, the offending character is left unread in the input stream. 

scanf returns the number of successfully matched and assigned input items; this number can be zero in the 
event of an early conflict between an input character and the control string. 

If the input ends before the first conflict or conversion, EOF is returned. If the input ends after the first 
conflict or conversion, the number of successfully matched items is returned. 

EXAMPLES 

The call; 



int i, n; float x; char name[50]; 
n = scanf ("%d%f%s", &i, &x, name); 

with the input line: 

25 54.32E-1 thompson 

will assign to n the value 3, to i the value 25, to x the value 5.432, and name will contain thompson\0. Or; 

int i; float x; char name[50]; 

(void) scanf (”%2d%f%*d %[0-9]", &i, &x, name); 

with input: 

56789 0123 56a72 

will assign 56 to i, 789.0 to x, skip 0123, and place the string 56\0 in name. The next call to getchar (see 
getc (3S)) will return a. 

SEE ALSO 

getc(3S), printf(3V) strtod(3), strtol(3), scanf(3S) 

DIAGNOSTICS 

These functions return EOF on end of input, and a short count for missing or illegal data items. 

BUGS 

The success of literal matches and suppressed assignments is not directly determinable. 

scarf cannot read the strings which printf{ 3 V) generates fcx TEEE indeterminate floating point values. 



382 



Last change: 18 February 1987 



Sun Release 3.4 




SC ANF ( 3V ) 



SYSTEM V COMPATIBILITY ROUTINES 



SCANF(3V) 



scarf provides no way to convert a number in any arbitrary base (decimal, hex or octal) based on the tradi- 
tional C conventions (leading 0 or Ox). 
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NAME 

setbuf, setbuffer, setlinebuf, setvbuf - assign buffering to a stream 

SYNOPSIS 

#include <stdio.h> 

setbuf(stream, buf) 

FILE ’stream; 
char *buf; 

setbuffer(stream, buf, size) 

FILE ’stream; 
char ’buf; 
int size; 

set!inebuf(stream) 

FILE ’stream; 

int setvbuf (stream, buf, type, size) 

FILE ’stream; 
char *buf; 
int type, size; 

DESCRIPTION 

The three types of buffering available are unbuffered, block buffered, and line buffered. When an output 
stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is 
block buffered many characters are saved up and written as a block; when it is line buffered characters are 
saved up until a newline is encountered or input is read from stdin. /flush (see /close (SS)) may be used to 
force the block out early. Normally all files are block buffered. A buffer is obtained from malloc{ 3) upon 
the first getc or putc (3S) on the file. 

By default, output to a terminal is line buffered and all other input/output is fully buffered. 

setbuf can be used after a stream has been opened but before it is read or written. It causes the array 
pointed to by buf to be used instead of an automatically allocated buffer. If buf is the NULL pointer, 
input/output will be completely unbuffered. A manifest constant BUFSIZ, defined in the <stdio.h> header 
file, tells how big an array is needed; 

char buf[BUFSIZ]; 

setbuffer, an alternate form of setbuf, can be used after a stream has been opened but before it is read or 
written. It causes the character array buf whose size is determined by the size argument to be used instead 
of an automatically allocated buffer. If buf is the NULL pointer, input/output will be completely unbuf- 
fered. 

setvbuf can be used after a stream has been opened but before it is read or written, type determines how 
stream will be buffered. Legal values for type (defined in <stdio.h>) are; 

IOFBF causes input/output to be fully buffered. 

IOLBF causes output to be line buffered; the buffer will be flushed when a newline is written, the 
buffer is full, or input is requested. 

_IONBF causes input/output to be completely unbuffered. If buf is not the NULL pointer, the array it 
points to will be used for buffering, instead of an automatically allocated buffer. Size 
specifies the size of the buffer to be used. 

setlinebuf is used to change the buffering on a stream from block buffered or unbuffered to line buffered. 
Unlike setbuf, setbuffer, and setvbuf, it can be used at any time that the file descriptor is active. 

A file can be changed from unbuffered or line buffered to block buffered by using /reopen (see/open(3S)). 
A file can be changed from block buffered or line buffered to unbuffered by using freopen followed by set- 
buf with a buffer argument of NULL. 
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NAME 

bwone - Sun-1 black and white frame buffer 
SYNOPSIS — SUN-2 

device bwoneO at mbmem ? csr OxcOOOO priority 3 
DESCRIPTION 

The bwone interface provides access to Sun-1 black and white graphics controller boards. It supports the 
ioctls described in fbio{ 4S). 

FILES 

Idevlbwonel 0-9] 

SEE ALSO 

mmap(2), fb(4S), fbio(4S) 

BUGS 

Use of vertical-retrace interrupts is not supported. 

The video state returned by the FBIOGVIDEO ioctl may be incorrect. It is not possible for the driver to 
determine the state of the hardware video enable bit, so it reports the last state stored by the FBIOSVIDEO 
ioctl. User processes which map the frame buffer can directly enable or disable the video, unknown to the 
driver. 
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NAME 

bwtwo - Sun-3/Sun-2 black and white frame buffer 
SYNOPSIS — SUN-3 

device bwtwoO at obmem 1 csr OxffOOOOOO priority 4 
device bwtwoO at obmem 2 csr 0x100000 priority 4 
device bwtwoO at obmem 3 csr OxffOOOOOO priority 4 
device bwtwoO at obmem 4 csr OxffOOOOOO 

The first synopsis line given above should be used to generate a kernel for a Sun-3/75 or Sun-3/160; the 
second, for a Sun-3/50; the third, for a Sun-3/260; and the fourth, for a Sun-3/ 110. 

SYNOPSIS — SUN-2 

device bwtwoO at obmem 1 csr 0x700000 priority 4 
device bwtwoO at obio 2 csr 0x0 priority 4 

The first synopsis line given above should be used to generate a kernel for a Sun-2/120 or Sun-2/170; the 
second, for a Sun-2/50 or Sun-2/ 160. 

DESCRIPTION 

The bwtwo interface provides access to Sun monochrome memory frame buffers. It supports the ioctls 
described in fbio{ 4S). 

If flags 0x1 is specified, frame buffer write operations are buffered through regular high-speed RAM. This 
“copy memory” mode of operation speeds frame buffer accesses, but consumes an extra 128K bytes of 
memory. Only the Sun-3/50, Sun-3/75, and Sun-3/160 support copy memory; on other systems a warning 
message will be printed and the flag will be ignored. 

Reading or writing to the frame buffer is not allowed — you must use the mmap( 2) system call to map the 
board into your address space. 

FILES 

/dev/bwtwo[0-9] 

SEE ALSO 

mmap(2), fb(4S), fbio(4S), cgfour(4S) 

BUGS 

Use of vertical-retrace interrupts is not supported. 
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NAME 

cgfour - Sun-3 color memory frame buffer 

SYNOPSIS — SUN-3 

device cgfourO at obmem 4 csr 

DESCRIPTION 

The cgfour is a color memory frame buffer with a monochrome overlay plane and an overlay enable plane 
implemented on the Sun-3/1 10 and Sun-3/160. It provides the standard frame buffer interface as defined in 
fbio( 4S). 

In addition to the ioctls described under fbw( 4s), the cgfour interface responds to two cgfour -specific 
colormap ioctls, FBIOPUTCMAP and FBIOGETCMAP. FBIOPUTCMAP returns no information other than 
success/failure via the ioctl return value. FBIOGETCMAP returns its information in the arrays pointed to by 
the red, green, and blue members of its fbcmap structure argument; fbcmap is defined in <sunlfbio.h> as: 
struct fbcmap { 



int 


index; 


/* first element (0 origin) ♦/ 


int 


count; 


/* number of elements */ 


unsigned char 


♦red; 


/* red color map elements */ 


unsigned char 


♦green; 


/* green color map elements ♦/ 


unsigned char 


♦blue; 


/* blue color map elements */ 



}; 

The driver uses color board vertical-retrace interrupts to load the colormap. 

FILES 

Idev/cgfourO 

SEE ALSO 

mmap(2), fbio(4S) 
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NAME 

cgone - Sun-1 coles' graphics interface 
SYNOPSIS — SUN-2 

device cgoneO at mbmem ? csr OxecOOO priority 3 
DESCRIPTION 

The cgone interface provides access to the Sun-1 color graphics controller board, which is normally sup- 
plied with a 13" or 19" RS170 color monitor. It provides the standard frame buffer interface as defined in 
ft bio (4S). 

It supports the FB IOGPIXRECT iocd which allows SunWindows to be run on it; see fbio (4S) 

The hardware consumes 16 kilobytes of Multibus memory space. The board starts at standard addresses 
0xE8000 or OxECOOO. The board must be configured for interrupt level 3. 

FILES 

/dev/cgone[0-9] 

SEE ALSO 

mmap(2), fbio(4S) 

BUGS 

Use of color board vertical-retrace interrupts is not supported. 
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NAME 

fbio - general properties of frame buffers 
DESCRIPTION 



All of the Sun frame buffers support the same general interface. Each responds to a FBIOGTYPE ioctl 
which returns information in a structure defined in < sunt fbio. h > : 


struct fbtype { 




int fb_type; 


1* as defined below */ 


int fbheight; 


/* in pixels *1 


int fb_width; 


/* in pixels */ 


int fbdepth; 


1* bits per pixel *1 


int fbcmsize; 


1* size of color map (entries) */ 


int fb size; 

}; 


1* total size in bytes */ 


#define FBTYPE SUN1BW 


0 


tdefine FBTYPE SUN1COLOR 


1 


#define FBTYPE SUN2BW 


2 


#define FBTYPE SUN2COLOR 


3 


#define FBTYPE SUN2GP 


4 


#define FBTYPE SUN4COLOR 


8 


Each device has an FBTYPE which is used by higher-level software to determine how to perform raster-op 
and other functions. Each device is used by opening it, doing an FBIOGTYPE ioctl to see which frame 
buffer type is present, and thereby selecting the appropriate device-management routines. 



Full-fledged frame buffers (that is, those that run SunWindows) implement an FBIOGPIXRECT ioctl, which 
returns a pixrect This call is made only from inside the kernel. The returned pixrect is used by win (4S) 
for cursor tracking and colormap loading. 



FBIOS VIDEO and FBIOG VIDEO are general-purpose ioctls for controlling possible video features of frame 
buffers. They are defined in < sun! fbio. h> . These ioctls either set or return the value of a flags integer. At 
this point, only the FBVIDEOON option is available, controlled by FBIOSVIDEO. FBIOG VIDEO returns the 
current video state. 

The FBIOSATTR and FBIOGATTR ioctls allow access to special features of newer frame buffers. They use 
the following structures as defined in <sun/fbio.h> : 

#define FB_ATTR_NDEVSPECIFIC 8 /* no. of device specific values *1 

#define FBATTRNEMUTYPES 4 /* no. of emulation types */ 



struct fbsattr { 

int flags; 

#define FB ATTR AUTOINIT 
#define FB_ATTR_DE V SPECIFIC 
int emutype; 



/* misc flags */ 

1 /* emulation auto init flag */ 

2 /* dev. specific stuff valid flag */ 
/* emulation type (-1 if unused) */ 



}; 



int dev_specific[FB_ATTR_NDEVSPECIFIC];/* catchall */ 



struct fbgattr { 
int 
int 

struct 

struct 

int 



realtype; /* real device type */ 

owner; /* PID of owner, 0 if myself *1 

fbtype fbtype; /* fbtype info for real device *1 

fbsattr sattr; /* see above */ 

emu types [FB ATTR NEMUTYPES] ; I* possible emulations *1 

/* (-1 if unused) */ 



}; 
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SEE ALSO 

mmap(2), bwone(4S), bwtwo(4S), cgone(4S), cgtwo(4S), cgfour(4S), gpone(4S), fb(4S), win(4S) 

BUGS 

FBIOSATTR and FBIOGATTR are only supported by the cgfour( 4S) frame buffer. 

The FBV1DEO ON flag my be incorrect for Sun-1 black and white frame buffers; see bwone( 4S). 
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NAME 

vp - Ikon 10071-5 Versatec parallel printer interface 

SYNOPSIS — SUN-2 

device vpO at inbio ? csr 

DESCRIPTION 

This Sun interface to the Versatec printer/plotter is supported by the Ikon parallel interface board, a word 
DMA device, which is output only. 

The Versatec is normally handled by the line printer spooling system and should not be accessed by the 
user directly. 

Opening the device IdevIvpO may yield one of two errors: ENXIO indicates that the device is already in 
use; EIO indicates that the device is offline. 

The printer operates in either print or plot mode. To set the printer into plot mode you should include 
<vcmd.h> and use the ioctl(2) call 

ioctl(f, VSETSTATE, plotmd); 

where plotmd is defined to be 

int plotmdQ = { VPLOT, 0, 0 }; 

When going back into print mode from plot mode you normally eject paper by sending it an EOT after put- 
ting into print mode: 

int prtmdO = { VPRINT, 0, 0 }; 

fflush(vp); 
f = fileno (vp); 

ioctl(f, VSETSTATE, prtmd); 
write(f, "\04", 1); 

FILES 

/ dev/vpO 

BUGS 

If you use the standard i/o library on the Versatec, be sure to explicitly set a buffer using setbuf, since the 
library will not use buffered output by default, and will run very slowly. 

Writes must start on even byte boundaries and be an even number of bytes in length. 
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NAME 

vpc - Systech VPC-2200 Versatec printer/plotter and Centronics printer interface 
SYNOPSIS — SUN-2 

device vpcO at mbio ? csr 0x480 priority 2 
device vpcl at mbio ? csr 0x500 priority 2 

DESCRIPTION 

This Sun interface to the Versatec printer/plotter and to Centronics printers is supported by the Systech 
parallel interface board, an output-only byte-wide DMA device. The device has one channel for Versatec 
devices and one channel for Centronics devices, with an optional long lines interface for Versatec devices. 

Devices attached to this interface are normally handled by the line printer spooling system and should not 
be accessed by the user directly. 

Opening the device /dev/vpcO or /dev/lpO may yield one of two errors: ENXIO indicates that the device is 
already in use; EIO indicates that the device is offline. 

The Versatec printer/plotter operates in either print or plot mode. To set the printer into plot mode you 
should include <vcmdJi> and use the ioctl( 2) call: 

ioctl(f, VSETSTATE, plotmd); 

where plotmd is defined to be 

int plotmdf] = { VPLOT, 0, 0 }; 

When going back into print mode from plot mode you normally eject paper by sending it an EOT after put- 
ting into print mode: 

int prtmd[ ] = { VPRINT, 0, 0 }; 

fflush(vpc); 
f = fileno(vpc); 
ioctl(f, VSETSTATE, prtmd); 
write(f, "\04", 1); 

FILES 

/ dev/vpcO 
/ dev/lpO 

BUGS 

If you use the standard I/O library on the Versatec, be sure to explicitly set a buffer using setbuf, since the 
library will not use buffered output by default, and will run very slowly. 
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NAME 

acct- execution accounting file 
SYNOPSIS 

#include <sys/acct.h> 

DESCRIPTION 

The acct (2) system call makes entries in an accounting file for each process that terminates. The account- 
ing file is a sequence of entries whose layout, as defined by the include file is: 

/* @(#)accth 1.1 86/07/07 SMI; from UCB 6.1 83/07/29*/ 



/* 

* Accounting structures; 

* these use a comp_t type which is a 3 bits base 8 

* exponent, 13 bit fraction “floating point” number. 
*/ 

typedef u_short compt; 



struct acct 

{ 

char ac_comm[10]; 

compt acjitime; 

compt acstime; 

compt acetime; 

timet acbtime; 

short ac_uid; 

short acgid; 

short acmem; 

compt ac_io; 

dev_t ac_tty; 

char acflag; 



/* Accounting command name */ 
/* Accounting user time */ 

/* Accounting system time */ 

/* Accounting elapsed time */ 

/* Beginning time */ 

/* Accounting user ID */ 

/* Accounting group ID */ 

/* average memory usage */ 

/* number of disk IO blocks */ 

/* control typewriter */ 

/* Accounting flag */ 



fdefine AFORK 0001 

#define ASU 0002 

fdefine ACOMPAT 0004 

#define ACORE 0010 

tdefine AXSIG 0020 



/* has executed fork, but no exec */ 
/* used super-user privileges */ 

/* used compatibility mode */ 

/* dumped core */ 

/* killed by a signal */ 



#ifdef KERNEL 
#ifdef SYSACCT 
struct acct acctbuf; 

struct vnode *acctp; 

#else 

fdefine acct() 

fendif 

fendif 

If the process does an execve (2), the first 10 characters of the filename appear in ac comm. The accounting 
flag contains bits indicating whether execve (2) was ever accomplished, and whether the process ever had 
super-user privileges. 

SEE ALSO 

acct(2), execve(2), sa(8) 



Sun Release 3.4 



Last change: 15 January 1983 



521 




ALIASES ( 5 ) 



FILE FORMATS 



ALIASES (5) 



NAME 

aliases, addresses, forward - addresses and aliases for sendmail(8) 

SYNOPSIS 

/etc/passwd 

/usr/lib/aliases 

/usr/lib/aliases.dir 

/usr/lib/aliases.pag 

"/.forward 

DESCRIPTION 

These files contain mail addresses or aliases, recognized by sendmail(8), for the local host: 

/etc/passwd Mail addresses (usernames) of local users. 

/usr/lib/aliases Aliases for the local host, in ASCII format. This file can be edited to add, update, or 
delete local mail aliases. 

/usr /lib/ aliases. { dir,pag} 

The aliasing information from lusr/liblaliases, in binary, dbm(3X) format for use by 
sendmailfS). The program newaliases{8), which is invoked automatically by send- 
mail(8), maintains these files. 

~ /.forward Addresses to which a user’s mail is forwarded (see Automatic Forwarding, below). 

In addition, the Yellow Pages aliases map mail.aliases contains addresses and aliases available for use 
across the network. 

ADDRESSES 

As distributed, sendmail(8) supports the following types of addresses: 

• Local usernames. These are listed in the local host’s /etc/passwd file. 

• Local filenames. When mailed to an absolute pathname, a message can be appeneded to a file. 

• Commands. If the first character of the address is a vertical bar, ( | ), sendmail (8) pipes die message 
to the standard input of the command the bar precedes. 

• DARPA-standard mail addresses of the form: 

name@doma in 

If domain does not contain any dots (.), then it is interpreted as the name of a host in the current 
domain. Otherwise, the message is passed to a mailhost that determines how to get to the specified 
domain. Domains are divided into subdomains separated by dots, with the top-level domain on the 
right Top-level domains include: 

.COM Commerical organizations. 

.EDU Educational organizations. 

.GOV Government organizations. 

.MIL Military organizations. 

For example, the lull address of John Smith could be: 

js@jsmachinePodunk-U.EDU 

if he uses the machine named "jsmachine" at Podunk University. 

• uucp(lC) addresses of the form: 

. . . [hostl]hostlusername 

These are sometimes mistakenly referred to as "Usenet" addresses. uucp(lC) provides links to 
numerous sites throughout the world for the remote copying of files. 
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Other site-specific forms of addressing can be added by customizing the sendmail configuration file. See 
the sendmail (i), and Sendmail Installation and Operation in System Administration for the Sun Worksta- 
tion for details. Standard addresses are recommended. 

ALIASES 

Local Aliases 

/usr/libf aliases is formatted as a series of lines of the form 
name : address[ 9 address] 

name is the name of the alias or alias group, and address is the address of a recipient in the group. Aliases 
can be nested. That is, an address can be the name of another alias group. Lines beginning with white 
space are treated as continuation lines for the preceding alias. Lines beginning with # are comments. 

Special Aliases 

An alias of the form: 

owntr— aliasname : address 

directs error-messages resulting from mail to alias-name to address , instead of back to the person who sent 
the message. 

An alias of the form: 

aliasname : :inclu deipathname 

with colons as shown, adds the recipients listed in the file pathname to the aliasname alias. This allows a 
private list to be maintained separately from the aliases file. 

YP Domain Aliases 

Normally, the aliases file on the master YP server is used for the mailaliases YP map, which can be made 
available to every YP client Thus, the fusrlliblaliases* files on the various hosts in a network will one day 
be obsolete. Domain-wide aliases should ultimately be resolved into usernames on specific hosts. For 
example, if the following were in the domain- wide alias file: 

jsmith:js@jsmachine 

then any YP client could just mail to "jsmith" and not have to remember the machine and user name for 
John Smith. If a YP alias does not resolve to an address with a specific host, then the name of the YP 
domain is used. There should be an alias of the domain name for a host in this case. For example, the 
alias: 

jsmith:root 

sends mail on a YP client to M root@podunk-u" if the name of the YP domain is "podunk-u". 

Automatic Forwarding 

When an alias (or address) is resolved to the name of a user on the local host, sendmail checks for a for- 
ward file, owned by the intended recipient, in that user’s home directory, and with universal read access. 
This file can contain one or more addresses or aliases as described above, each of which is sent a copy of 
the user’s mail. 

Care must be taken to avoid creating addressing loops in the forward file. When forwarding mail between 
machines, be sure that the destination machine does not return the mail to the sender through the operation 
of any YP aliases. Otherwise, copies of the message may "bounce.” Usually, the solution is to change the 
YP alias to direct mail to the proper destination. 

A backslash before a username inhibits further aliasing. For instance, to invoke the vacation ( 1) program, 
user js creates a forward file that contains the line: 

\js, " I /usr/ucb/vacation js” 
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so that one copy of the message is sent to the user, and another is piped into the vacation (l) program. 

SEE ALSO 

newaliases(8), dbm(3X), sendmail(8), uucp(lC), vacation(l) 

System Administration for the Sun Workstation 

BUGS 

Because of restrictions in dbm{ 3X) a single alias cannot contain more than about 1000 characters. Nested 
aliases can be used to circumvent this limit. 
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